kaiten-mcp

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)

| Tool | Description | |------|-------------| | kaiten_get_card | Get card by ID, with optional children | | kaiten_search_cards | Search cards with 15+ filters, dates, pagination | | kaiten_get_space_cards | Cards in a space | | kaiten_get_board_cards | Cards on a board | | kaiten_create_card | Create a new card | | kaiten_update_card | Update fields, move between columns/boards, set custom property values | | kaiten_delete_card | Delete a card (fails if it has logged time — delete time logs first) | | kaiten_get_card_location_history | Audit trail: how long the card sat in each column (Wave 5) |

Comments (4)

| Tool | Description | |------|-------------| | kaiten_get_card_comments | List comments for a card | | kaiten_create_comment | Add a comment | | kaiten_update_comment | Update a comment | | kaiten_delete_comment | Delete a comment |

Time logs (6)

| Tool | Description | |------|-------------| | kaiten_get_user_timelogs | Time logs for a user in a date range | | kaiten_get_card_timelogs | Time logs for a card | | kaiten_create_timelog | Create a time-log entry (requires roleId) | | kaiten_update_timelog | Update a time-log entry | | kaiten_delete_timelog | Delete a time-log entry (requires cardId) | | kaiten_get_timesheet | Global timesheet across users/spaces/boards (Wave 5) |

Spaces & boards (9)

| Tool | Description | |------|-------------| | kaiten_list_spaces | List all spaces | | kaiten_get_space | Get space by ID | | kaiten_list_boards | List boards in a space | | kaiten_get_board | Get board by ID (with inline columns/lanes at verbosity=max) | | kaiten_list_columns | Columns (statuses) of a board | | kaiten_list_subcolumns | Sub-columns inside a parent column (Wave 5) | | kaiten_list_lanes | Lanes (swimlanes) of a board | | kaiten_list_card_types | Card types (global to the company) | | kaiten_list_space_users | Users assigned to a specific space |

Subtasks (3)

| Tool | Description | |------|-------------| | kaiten_list_subtasks | List child cards | | kaiten_attach_subtask | Attach a card as a subtask | | kaiten_detach_subtask | Detach a subtask |

Tags (4)

| Tool | Description | |------|-------------| | kaiten_list_card_tags | Tags currently on a card | | kaiten_list_workspace_tags | All tags defined in the workspace | | kaiten_add_tag | Add a tag to a card (auto-creates the tag if it doesn't exist) | | kaiten_remove_tag | Remove a tag from a card |

Checklists (7)

| Tool | Description | |------|-------------| | kaiten_get_checklist | Get a checklist with its items | | kaiten_create_checklist | Create a new checklist on a card | | kaiten_delete_checklist | Delete a checklist | | kaiten_rename_checklist | Rename a checklist | | kaiten_add_checklist_item | Add an item to a checklist | | kaiten_update_checklist_item | Update an item (text, checked, due date, responsible) | | kaiten_delete_checklist_item | Delete a checklist item |

Files (3)

| Tool | Description | |------|-------------| | kaiten_list_files | List card attachments | | kaiten_upload_file | Upload a file to a card | | kaiten_delete_file | Delete a card attachment |

Custom fields (2)

| Tool | Description | |------|-------------| | kaiten_list_custom_properties | List custom properties available in the workspace | | kaiten_list_custom_property_select_values | List allowed values for a select / multi_select property (Wave 5) |

Users (3)

| Tool | Description | |------|-------------| | kaiten_get_current_user | The authenticated user | | kaiten_list_users | All users in the workspace | | kaiten_list_company_roles | Roles defined at the company level (renamed from get_user_roles) |

Card members (4) — Wave 4

| Tool | Description | |------|-------------| | kaiten_list_card_members | Members assigned to a card | | kaiten_add_card_member | Add a user as a card member | | kaiten_remove_card_member | Remove a member from a card | | kaiten_set_card_responsible | Set the responsible user (the card always has an owner — only re-assignment) |

Card blockers (4) — Wave 4

| Tool | Description | |------|-------------| | kaiten_list_card_blockers | Blockers on a card | | kaiten_add_card_blocker | Add a blocker (free-form reason or referencing another card) | | kaiten_update_card_blocker | Update blocker reason or referenced card | | kaiten_release_card_blocker | Release a blocker (soft release — flips released:true, the row stays in the list) |

Card external links (4) — Wave 5

| Tool | Description | |------|-------------| | kaiten_list_card_external_links | List external links on a card | | kaiten_add_card_external_link | Link the card to a Jira ticket, GitHub issue, etc. | | kaiten_update_card_external_link | Update a link's URL or description | | kaiten_remove_card_external_link | Remove a link (true hard-delete, unlike blockers) |

Sprints (2) — Wave 5

| Tool | Description | |------|-------------| | kaiten_list_sprints | List sprints visible to the user | | kaiten_get_sprint | Get a sprint summary with its cards |

Resources

| URI | Description | |-----|-------------| | kaiten://spaces | All spaces with IDs and titles | | kaiten://boards | All boards across spaces (id, title, spaceId) |

Prompts

| Name | Description | |------|-------------| | create-card | Step-by-step card creation workflow | | time-report | Time tracking report for a date range | | board-overview | Summarize a board: columns, cards, overdue items |

---

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.

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | KAITEN_API_TOKEN | yes | — | API token (Bearer) | | KAITEN_URL | yes | — | Kaiten instance URL, e.g. https://your-company.kaiten.ru | | KAITEN_DEFAULT_SPACE_ID | no | — | Default space ID for kaiten_search_cards when spaceId is omitted. Without it, the LLM will discover spaces via kaiten_list_spaces first time it needs to search — costs one extra round-trip. Useful if you have many spaces and want to pin search to one. | | KAITEN_REQUEST_TIMEOUT_MS | no | 10000 | HTTP request timeout in milliseconds | | KAITEN_CACHE_TTL_MS | no | 300000 | TTL for cached reference data (spaces, boards, users, roles) | | KAITEN_ALLOWED_SPACE_IDS | no | — | Comma-separated whitelist of space IDs the AI can access (multi-team safety) | | KAITEN_ALLOWED_BOARD_IDS | no | — | Comma-separated whitelist of board IDs |

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):

| Level | Description | |-------|-------------| | min | Compact response, saves LLM context — only key fields | | normal | Common fields — strict superset of min | | max | Full detail — strict superset of normal, includes nested children where relevant | | raw | Unprocessed API response, no transformation |

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