kaiten-mcp

Русский

Why kaiten-mcp exists

MCP server for Kaiten — 63 tools covering cards, comments, checklists, time tracking, members, blockers, sprints, custom properties, external links, file uploads, location history, and a global timesheet.

Connect Cursor, Claude Desktop, Claude Code, or any MCP client to your Kaiten workspace.

Start with a single command: npx -y kaiten-mcp.

This is a fork of iamtemazhe/mcp-kaiten with extensive Wave 1–5 fixes: 22 net new tools, schema repairs, preflight checks, response simplification ladders, and reliability improvements. See WHYIEXIST.md and the CHANGELOG.

Quick Start

1. Get an API token

1. Open your Kaiten instance (e.g. https://your-company.kaiten.ru)
2. Profile → API Key
3. Create a token and copy it

2. Add to your MCP client

{
  "mcpServers": {
    "kaiten": {
      "command": "npx",
      "args": ["-y", "kaiten-mcp"],
      "env": {
        "KAITEN_API_TOKEN": "your-api-token",
        "KAITEN_URL": "https://your-company.kaiten.ru"
      }
    }
  }
}

That's it. The server starts automatically when the MCP client connects. There is no user_id to configure — the current user is resolved automatically from the token.

What can it do?

63 tools across 14 families. Every tool accepts an optional verbosity parameter (min / normal / max / raw) to control response size.

Cards (8)

Comments (4)

Time logs (6)

Spaces & boards (9)

Subtasks (3)

Tags (4)

Checklists (7)

Files (3)

Custom fields (2)

Users (3)

Card members (4) — Wave 4

Card blockers (4) — Wave 4

Card external links (4) — Wave 5

Sprints (2) — Wave 5

Resources

Prompts

Authentication

Kaiten uses API tokens. OAuth is not supported by the Kaiten API.

1. Profile → API Key in your Kaiten instance
2. Create a token, copy it
3. Set KAITEN_API_TOKEN and KAITEN_URL in your MCP client config

The current user is detected automatically — you don't need to set a user ID anywhere.

Environment variables

Only two variables are required: KAITEN_API_TOKEN and KAITEN_URL. Everything else is optional and exists for performance/safety tuning.

Finding IDs from the browser URL

You don't need a developer console — every Kaiten ID is visible in the browser address bar.

• Space ID — click a space in the left menu, look at the URL: https://your-company.kaiten.ru/space/762572 → space ID is 762572.
• Board ID — click a board, look at the URL: https://your-company.kaiten.ru/space/762572/boards/1727446 → board ID is 1727446.
• Card ID — open a card, look at the URL: https://your-company.kaiten.ru/space/762572/card/63258149 → card ID is 63258149 (also visible in the card header as #63258149).

These are the values you put into KAITEN_DEFAULT_SPACE_ID, KAITEN_ALLOWED_SPACE_IDS, and KAITEN_ALLOWED_BOARD_IDS.

Verbosity

Every tool accepts an optional verbosity parameter (default: min):

The min → normal → max ladder is a strict superset chain (Wave 4 PR 4.6) — anything visible at min is also visible at normal and max.

Reliability

• Cross-resource preflight (Wave 4 PR 4.7): mutating tools that take both a parent ID and a child ID (e.g. card + comment, card + checklist) verify the child belongs to the parent before sending the mutation. Prevents silent cross-resource bugs.
• Author enrichment (Wave 2): comment/timelog responses include author_name even when the API returns only author_id — the current user's name is filled in client-side.
• Context-aware error hints (Wave 4 PR 4.5): error messages from the API include a hint about which related read tool to call to recover (e.g. "404 on /cards/{id} → try kaiten_search_cards").
• Automatic retries: failed requests (429, 5xx, network errors, timeouts) are retried up to 3 times with exponential backoff and jitter. The Retry-After header is honored.
• Idempotency: write requests include idempotency keys to prevent duplicate mutations on retries.
• Caching: spaces, boards, users, roles cached in-memory with configurable TTL. Stale data is returned immediately while a background refresh runs.
• Crash protection: unhandled errors are logged without crashing the server.
• Response truncation: very large responses are auto-truncated to protect the LLM context window.

Kaiten API quirks worth knowing

These are real Kaiten-side behaviors discovered during Wave 4–5 implementation. Each is mitigated in the corresponding tool, but the LLM will see them in tool descriptions.

• update_card.state is read-only. The card's state is computed from column.type (1→queued, 2→in_progress, 3→done). To change state, move the card with column_id.
• update_card.size doesn't accept a number. Use sizeText: "5 SP" (sent as size_text) or estimate_workload in seconds.
• owner_id cannot be cleared. Cards always have an owner. You can only re-assign, not remove.
• Empty PATCH /cards/{id} returns 403 (a quirk of the API itself). The server validates this client-side and returns a clearer error.
• Blocker DELETE is a soft release. It flips released:true but keeps the row in the list endpoint. The tool is named kaiten_release_card_blocker (not remove_*) to make this explicit.
• External-link DELETE is a true hard-delete. Asymmetric with blockers — the link disappears.
• location_history.id is a string, not a number — it's preserved as-is (Number-parsing would lose precision for IDs > 2^53).
• Sprint not-found returns 403, not 404. Both are handled by the error hint helper.
• Timesheet rejects empty array filters. card_ids= (empty value) returns 400. Empty arrays are skipped from the query string entirely.
• Card descriptions and comments default to markdown. Kaiten's UI renders descriptions and comments as markdown. If you send raw HTML without telling Kaiten, the angle brackets stay in the body and the UI shows them as literal text. To send HTML, pass textFormat: 'html' to kaiten_create_card / kaiten_update_card / kaiten_create_comment / kaiten_update_comment — the server will then parse and normalize. Discovered live during the 0.1.1 → 0.1.2 dogfooding round (cards use the documented text_format_type_id; comments use an undocumented type field that we verified works).
• Workspace tags can't be deleted via the API. Kaiten's /tags endpoint only supports GET and POST (verified docs/api/tags/). kaiten_remove_tag only detaches a tag from a card — it doesn't remove it from the workspace pool. Orphan workspace tags accumulate over time and can only be cleaned up via the Kaiten admin UI.

LLM Guide

The package ships with LLM_GUIDE.md — a comprehensive reference designed to be read by an LLM before it starts using the tools. It covers the Kaiten object hierarchy, common workflows, API quirks, error recovery patterns, and a tool selection quick-reference.

How to use it

Add this line to your project's CLAUDE.md (or equivalent instructions file):

Read ./node_modules/kaiten-mcp/LLM_GUIDE.md before working with Kaiten.

This gives the LLM full context about Kaiten's data model and the non-obvious behaviors (like state being computed from column.type, or blocker soft-release semantics) before it makes its first tool call.

The guide is included in the npm package — it's available at node_modules/kaiten-mcp/LLM_GUIDE.md after npx -y kaiten-mcp runs.

Troubleshooting

• Server won't start: check that KAITEN_API_TOKEN and KAITEN_URL are set in the MCP config env block.
• 401 errors: the token may be expired or invalid — generate a new one in your Kaiten profile.
• Large responses: use filters (boardId, spaceId) or lower the limit.
• 403 on a write operation: check the card isn't archived and that your token has write access to the space.

Contributing

Contributions are welcome! See CONTRIBUTING.md for setup instructions, code style, and PR guidelines.

Changelog · Contributing · License