kaiten-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@kaiten-mcp show me cards in the 'In Progress' column on board 5"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
kaiten-mcp
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
Open your Kaiten instance (e.g.
https://your-company.kaiten.ru)Profile → API Key
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.
Related MCP server: kaiten-mcp
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 |
| Get card by ID, with optional children |
| Search cards with 15+ filters, dates, pagination |
| Cards in a space |
| Cards on a board |
| Create a new card |
| Update fields, move between columns/boards, set custom property values |
| Delete a card (fails if it has logged time — delete time logs first) |
| Audit trail: how long the card sat in each column (Wave 5) |
Comments (4)
Tool | Description |
| List comments for a card |
| Add a comment |
| Update a comment |
| Delete a comment |
Time logs (6)
Tool | Description |
| Time logs for a user in a date range |
| Time logs for a card |
| Create a time-log entry (requires |
| Update a time-log entry |
| Delete a time-log entry (requires |
| Global timesheet across users/spaces/boards (Wave 5) |
Spaces & boards (9)
Tool | Description |
| List all spaces |
| Get space by ID |
| List boards in a space |
| Get board by ID (with inline columns/lanes at |
| Columns (statuses) of a board |
| Sub-columns inside a parent column (Wave 5) |
| Lanes (swimlanes) of a board |
| Card types (global to the company) |
| Users assigned to a specific space |
Subtasks (3)
Tool | Description |
| List child cards |
| Attach a card as a subtask |
| Detach a subtask |
Tags (4)
Tool | Description |
| Tags currently on a card |
| All tags defined in the workspace |
| Add a tag to a card (auto-creates the tag if it doesn't exist) |
| Remove a tag from a card |
Checklists (7)
Tool | Description |
| Get a checklist with its items |
| Create a new checklist on a card |
| Delete a checklist |
| Rename a checklist |
| Add an item to a checklist |
| Update an item (text, checked, due date, responsible) |
| Delete a checklist item |
Files (3)
Tool | Description |
| List card attachments |
| Upload a file to a card |
| Delete a card attachment |
Custom fields (2)
Tool | Description |
| List custom properties available in the workspace |
| List allowed values for a |
Users (3)
Tool | Description |
| The authenticated user |
| All users in the workspace |
| Roles defined at the company level (renamed from |
Card members (4) — Wave 4
Tool | Description |
| Members assigned to a card |
| Add a user as a card member |
| Remove a member from a card |
| Set the responsible user (the card always has an owner — only re-assignment) |
Card blockers (4) — Wave 4
Tool | Description |
| Blockers on a card |
| Add a blocker (free-form reason or referencing another card) |
| Update blocker reason or referenced card |
| Release a blocker (soft release — flips |
Card external links (4) — Wave 5
Tool | Description |
| List external links on a card |
| Link the card to a Jira ticket, GitHub issue, etc. |
| Update a link's URL or description |
| Remove a link (true hard-delete, unlike blockers) |
Sprints (2) — Wave 5
Tool | Description |
| List sprints visible to the user |
| Get a sprint summary with its cards |
Resources
URI | Description |
| All spaces with IDs and titles |
| All boards across spaces (id, title, spaceId) |
Prompts
Name | Description |
| Step-by-step card creation workflow |
| Time tracking report for a date range |
| Summarize a board: columns, cards, overdue items |
Authentication
Kaiten uses API tokens. OAuth is not supported by the Kaiten API.
Profile → API Key in your Kaiten instance
Create a token, copy it
Set
KAITEN_API_TOKENandKAITEN_URLin 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 |
| yes | — | API token (Bearer) |
| yes | — | Kaiten instance URL, e.g. |
| no | — | Default space ID for |
| no |
| HTTP request timeout in milliseconds |
| no |
| TTL for cached reference data (spaces, boards, users, roles) |
| no | — | Comma-separated whitelist of space IDs the AI can access (multi-team safety) |
| 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 is762572.Board ID — click a board, look at the URL:
https://your-company.kaiten.ru/space/762572/boards/1727446→ board ID is1727446.Card ID — open a card, look at the URL:
https://your-company.kaiten.ru/space/762572/card/63258149→ card ID is63258149(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 |
| Compact response, saves LLM context — only key fields |
| Common fields — strict superset of |
| Full detail — strict superset of |
| 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_nameeven when the API returns onlyauthor_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}→ trykaiten_search_cards").Automatic retries: failed requests (429, 5xx, network errors, timeouts) are retried up to 3 times with exponential backoff and jitter. The
Retry-Afterheader 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.stateis read-only. The card'sstateis computed fromcolumn.type(1→queued, 2→in_progress, 3→done). To change state, move the card withcolumn_id.update_card.sizedoesn't accept a number. UsesizeText: "5 SP"(sent assize_text) orestimate_workloadin seconds.owner_idcannot 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
DELETEis a soft release. It flipsreleased:truebut keeps the row in the list endpoint. The tool is namedkaiten_release_card_blocker(notremove_*) to make this explicit.External-link
DELETEis a true hard-delete. Asymmetric with blockers — the link disappears.location_history.idis 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'tokaiten_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 documentedtext_format_type_id; comments use an undocumentedtypefield that we verified works).Workspace tags can't be deleted via the API. Kaiten's
/tagsendpoint only supportsGETandPOST(verifieddocs/api/tags/).kaiten_remove_tagonly 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_TOKENandKAITEN_URLare set in the MCP configenvblock.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 thelimit.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.
Available Tools
63 toolskaiten_add_card_blockerAdd Card BlockerA
Block a card. At least one of reason (free-text) or blockerCardId (pointer to blocking card) must be provided. A card blocker can have BOTH: e.g., blockerCardId=42 plus reason='waiting for the design review on that card'. Returns: the created blocker object.
Inputs: cardId (required), reason, verbosity, blockerCardId.
kaiten_add_card_external_linkAdd Card External LinkA
Attach an external link (URL) to a card. Useful for linking to Jira issues, GitHub PRs, design docs, etc., without bloating the card description. url must be a valid URL (max 16384 chars). description is optional (max 512 chars). cardId from kaiten_get_card. Returns: the created link (simplified per verbosity). NOTE: the POST response does not carry card_id / external_link_id — those fields only appear in the subsequent kaiten_list_card_external_links response.
Inputs: url (required), cardId (required), verbosity, description.
kaiten_add_card_memberAdd Card MemberAIdempotent
Attach a user to a card as a member. The user will be listed by kaiten_list_card_members with type=1 (member). Use kaiten_set_card_responsible to promote an existing member to type=2 (responsible). userId from kaiten_list_users or kaiten_list_space_users. Returns: the added user (simplified per verbosity) including the type field.
Inputs: cardId (required), userId (required), verbosity.
kaiten_add_checklist_itemAdd Checklist ItemA
Add a checklist item. text has a 4096-character limit (Kaiten server-side cap). Item supports text and checked state only — due_date and responsible_id are not exposed by this fork. checklistId from kaiten_create_checklist or kaiten_get_checklist; edit with kaiten_update_checklist_item.
Inputs: text (required), cardId (required), checklistId (required), verbosity.
kaiten_add_tagAdd Card TagAIdempotent
Attach a tag to a card by name. cardId from kaiten_search_cards or kaiten_get_card. If a tag with this name does not yet exist in the workspace, Kaiten will auto-create it (and it will then also appear in kaiten_list_workspace_tags). Returns the tag object (including its ID, which you need for kaiten_remove_tag). Idempotent — re-adding the same tag name returns the same tagId (no duplicate).
Inputs: name (required), cardId (required).
kaiten_attach_subtaskAttach SubtaskAIdempotent
Link an existing child card to a parent card. Subtask = a real Kaiten card linked as a child (NOT a checklist item — for to-do items use kaiten_add_checklist_item). Child via kaiten_create_card; verify via kaiten_list_subtasks. Idempotent — re-attaching the same pair returns success without creating a duplicate link. Cycles (A→B and B→A) and cross-board attaches are accepted by Kaiten without warning.
Inputs: childCardId (required), parentCardId (required).
kaiten_create_cardCreate CardA
Create card. Requires boardId (from kaiten_list_boards) and columnId (from kaiten_list_columns). Optional: laneId (kaiten_list_lanes), typeId (kaiten_list_card_types), sizeText. ownerId must be a positive integer (Kaiten requires every card to have an owner). NOTE: response in min/normal verbosity may show board_title:null and column_title:null because POST /cards returns a flat payload. Re-fetch via kaiten_get_card to populate, or use verbosity=raw.
Inputs: title (required), boardId (required), columnId (required), asap, +10 more.
kaiten_create_checklistCreate ChecklistA
Create an empty checklist on a card. Add rows with kaiten_add_checklist_item; read back with kaiten_get_checklist.
Inputs: name (required), cardId (required), verbosity.
kaiten_create_commentCreate CommentA
Add a comment to a card. Markdown by default — if you are sending HTML, also pass textFormat: 'html' so Kaiten stores and renders the comment as HTML. Without that hint, raw HTML shows up in the UI as literal angle brackets. QUIRK: Kaiten's comment markdown parser is a CommonMark subset and does NOT support ATX headings (### Header) — they render as literal text. Bold, italic, lists, inline code, code blocks, links and blockquotes all work. Card DESCRIPTION markdown does support headings — the limitation is comment-specific. Use plain bold or switch to HTML if you need a heading inside a comment. Resolve cardId via kaiten_search_cards or kaiten_get_card; list existing comments via kaiten_get_card_comments. Returns: the created comment object (including its id, needed for kaiten_update_comment / kaiten_delete_comment).
Inputs: text (required), cardId (required), verbosity, textFormat.
kaiten_create_timelogCreate TimelogA
Log time (in minutes) on a card. roleId from kaiten_list_company_roles; cardId from kaiten_search_cards; verify with kaiten_get_card_timelogs.
Inputs: cardId (required), roleId (required), timeSpentMinutes (required), comment, +2 more.
kaiten_delete_cardDelete CardADestructive
Permanently delete a card (cannot be undone). Resolve cardId via kaiten_search_cards or kaiten_get_card. NOTE: cards with logged time cannot be deleted (Kaiten returns 400 'Card removing with logged time not allowed'). Delete the timelogs first via kaiten_delete_timelog.
Inputs: cardId (required).
kaiten_delete_checklistDelete ChecklistADestructive
Delete checklist and all items (irreversible). checklistId from kaiten_get_checklist or kaiten_get_card.
Inputs: cardId (required), checklistId (required).
kaiten_delete_checklist_itemDelete Checklist ItemADestructive
Remove a single item from a checklist. cardId, checklistId, and itemId all from kaiten_get_checklist. NOTE: Kaiten resolves the item by itemId alone — wrong cardId/checklistId still deletes the real item. Verify the pair before deleting.
Inputs: cardId (required), itemId (required), checklistId (required).
kaiten_delete_commentDelete CommentADestructive
Delete comment. commentId and cardId from kaiten_get_card_comments.
Inputs: cardId (required), commentId (required).
kaiten_delete_fileDelete FileADestructiveIdempotent
Remove an attachment. fileId and cardId come from kaiten_list_files. Re-delete of an already-deleted file returns success silently (Kaiten side is idempotent).
Inputs: cardId (required), fileId (required).
kaiten_delete_timelogDelete TimelogADestructive
Delete a timelog. WARNING: Kaiten ignores cardId in the URL path and resolves the log purely by logId — passing a wrong cardId will still delete the log from its real owner card. Always verify the pair via kaiten_get_card_timelogs(cardId) before deleting.
Inputs: logId (required), cardId (required).
kaiten_detach_subtaskDetach SubtaskAIdempotent
Unlink child from parent; cards stay. Inverse of kaiten_attach_subtask. WARNING: Detaching a non-existent or wrong-pair link returns success silently. Verify the link exists via kaiten_list_subtasks(parentCardId) before relying on the success message.
Inputs: childCardId (required), parentCardId (required).
kaiten_get_boardGet BoardARead-onlyIdempotent
Get board metadata. verbosity=max returns inline columns and lanes — no need to call kaiten_list_columns / kaiten_list_lanes separately for a board overview. boardId from kaiten_list_boards.
Inputs: boardId (required), verbosity.
kaiten_get_board_cardsList Board CardsARead-onlyIdempotent
Recent cards on a board (newest first, no filters). For filtered search use kaiten_search_cards.
Inputs: boardId (required), limit, offset, condition, +1 more.
kaiten_get_cardGet CardARead-onlyIdempotent
Get a single card by ID. Use verbosity=max for full detail (default is min, which returns 9 core fields). Set includeChildren=true to also fetch child cards. Resolve cardId via kaiten_search_cards or kaiten_get_board_cards. Returns: a single card object (simplified per verbosity).
Inputs: cardId (required), verbosity, includeChildren.
kaiten_get_card_commentsList Card CommentsARead-onlyIdempotent
List all comments on a card. Each comment exposes its id — pass it as commentId to kaiten_update_comment or kaiten_delete_comment. Resolve cardId via kaiten_search_cards or kaiten_get_card. Returns: array of comments (simplified per verbosity).
Inputs: cardId (required), verbosity.
kaiten_get_card_location_historyGet Card Location HistoryARead-onlyIdempotent
Get the card movement history — every time the card was moved between boards, columns, lanes, or sprints, with a timestamp and the author who performed the move. Useful for audit ('who moved this card and when') and cycle-time analytics ('how long did this card sit in each column'). Sorted newest-first by changed. NOTE: unlike most Kaiten endpoints the history id field is a STRING (not an integer) — treat it as an opaque identifier. condition: 1=Active, 2=Archived, 3=Deleted. cardId from kaiten_get_card or kaiten_search_cards.
Inputs: cardId (required), verbosity.
kaiten_get_card_timelogsList Card TimelogsARead-onlyIdempotent
List a card's timelogs. Returns array; time_spent is in minutes. logId is used by kaiten_update_timelog / kaiten_delete_timelog; cardId from kaiten_search_cards. NOTE: returns [] for nonexistent cards as well as cards with no timelogs — verify cardId via kaiten_search_cards if you need to distinguish.
Inputs: cardId (required), verbosity.
kaiten_get_checklistGet ChecklistARead-onlyIdempotent
Get a checklist with its items. NOTE: Kaiten resolves checklists by checklistId alone — passing a wrong cardId still returns the real checklist if checklistId is valid. Verify via the returned checklist's parent card if cardId is reconstructed from memory. checklistId from kaiten_create_checklist or kaiten_get_card (verbosity=max).
Inputs: cardId (required), checklistId (required), verbosity.
kaiten_get_current_userGet Current UserARead-onlyIdempotent
Current user (id, name, email). id for kaiten_get_user_timelogs and kaiten_search_cards.ownerId. Calling this also warms an internal cache used by enrichAuthor for comments and timelogs — so author_name is populated on create_comment / create_timelog responses instead of coming back null.
Inputs: verbosity.
kaiten_get_spaceGet SpaceARead-onlyIdempotent
Fetch one space by ID including settings and allowed card types at verbosity=normal/max. Typical drill-down: kaiten_list_boards(spaceId) for the boards in this space, kaiten_list_space_users(spaceId) for members. spaceId from kaiten_list_spaces.
Inputs: spaceId (required), verbosity.
kaiten_get_space_cardsList Space CardsARead-onlyIdempotent
Recent cards in a space (newest first, no filters). For filtered search use kaiten_search_cards.
Inputs: spaceId (required), limit, offset, condition, +1 more.
kaiten_get_sprintGet Sprint SummaryARead-onlyIdempotent
Get a full sprint summary: sprint metadata PLUS the cards in the sprint, their version history (cardUpdates), and the custom properties used. The response is LARGE at verbosity=max — prefer min (returns cards_count only) or normal (returns brief {id,title,state} per card) unless you specifically need cardUpdates or customProperties. excludeDeletedCards filters out cards in condition=3 (deleted). Returns 404 if the sprintId is not found, 403 if the caller has no access to the sprint's space. sprintId from kaiten_list_sprints.
Inputs: sprintId (required), verbosity, excludeDeletedCards.
kaiten_get_timesheetGet Global TimesheetARead-onlyIdempotent
Get the global timesheet across cards and users for a date range — answers 'who logged how much time on which cards last week'. from and to are REQUIRED (YYYY-MM-DD; the API returns 400 without them). Optional array filters narrow by users, cards, boards, spaces, columns, tags, or groups — pass JSON arrays, the handler joins them with commas internally. Empty arrays are skipped entirely (passing an empty filter would itself return 400). For per-user timelogs prefer kaiten_get_user_timelogs; for per-card prefer kaiten_get_card_timelogs. Returns an array of timelog objects, each with author_id / author_name enriched when the author is the API caller. limit max 200.
Inputs: to (required), from (required), limit, offset, +8 more.
kaiten_get_user_timelogsList User TimelogsARead-onlyIdempotent
List a user's timelogs across cards. Returns array; time_spent is in minutes. from/to in YYYY-MM-DD format. userId from kaiten_get_current_user or kaiten_list_users. Card titles via kaiten_get_card.
Inputs: to (required), from (required), userId (required), verbosity.
kaiten_list_boardsList BoardsARead-onlyIdempotent
List boards in a space. boardId feeds kaiten_get_board, kaiten_list_columns, kaiten_list_lanes, kaiten_get_board_cards, kaiten_search_cards, kaiten_create_card, and kaiten_update_card. spaceId from kaiten_list_spaces.
Inputs: spaceId (required), verbosity.
kaiten_list_card_blockersList Card BlockersARead-onlyIdempotent
List all blockers on a card, INCLUDING released ones (released:true rows are kept in history). Filter by the released field client-side to find currently-active blockers. Each blocker has either a free-text reason, a pointer to a blocking card (blocker_card_id + blocker_card_title), or both. Release a blocker via kaiten_release_card_blocker (which uses Kaiten's DELETE endpoint as a soft release — there is no hard-delete API). cardId from kaiten_search_cards. Returns: array of blocker objects (simplified per verbosity).
Inputs: cardId (required), verbosity.
kaiten_list_card_external_linksList Card External LinksARead-onlyIdempotent
List external links attached to a card. External links are URLs (Jira issues, GitHub PRs, design docs, etc.) that live in their own UI section on the card — separate from the card description, so attaching one does not pollute the description text. Returns id, url, description plus timestamps. Empty array if the card has no external links. cardId from kaiten_get_card or kaiten_search_cards.
Inputs: cardId (required), verbosity.
kaiten_list_card_membersList Card MembersARead-onlyIdempotent
List users assigned to a card (members and the responsible user). Each row carries type: 1=member, 2=responsible. cardId from kaiten_search_cards or kaiten_get_card. Returns: array of user objects (per verbosity) with a type field added.
Inputs: cardId (required), verbosity.
kaiten_list_card_tagsList Card TagsARead-onlyIdempotent
List tags currently attached to a card. Endpoint: GET /cards/{card_id}/tags. cardId from kaiten_search_cards or kaiten_get_card. To create a new tag, just call kaiten_add_tag with a name; Kaiten auto-creates missing tags on demand. For the workspace-wide tag pool (across all cards), use kaiten_list_workspace_tags.
Inputs: cardId (required).
kaiten_list_card_typesList Card TypesARead-onlyIdempotent
Card types defined globally per company (NOT per-board — a per-board endpoint does not exist). Returns Bug, Story, Feature, etc. typeId for kaiten_create_card or kaiten_update_card.
Inputs: verbosity.
kaiten_list_columnsList ColumnsARead-onlyIdempotent
Board columns (statuses). Each column has a col_type (1=queued, 2=in_progress, 3=done) — THIS is the mechanism for moving card state: pass the columnId of a column with the desired type to kaiten_update_card to change the card's state. columnId for kaiten_create_card, kaiten_update_card. boardId from kaiten_list_boards.
Inputs: boardId (required), verbosity.
kaiten_list_company_rolesList Company RolesARead-onlyIdempotent
Global role definitions for the company. id → kaiten_create_timelog.roleId. NOTE: the system 'Employee' role has id -1, which is valid for kaiten_create_timelog but would fail .positive() validation — that's why roleId on create_timelog/update_timelog is not strict-positive.
Inputs: verbosity.
kaiten_list_custom_propertiesList Custom PropertiesARead-onlyIdempotent
List company-wide custom property definitions (custom fields). In Kaiten, custom properties are global per company/workspace, not per space. The type field on each property determines the value shape when writing via kaiten_update_card.properties: string | number | date | select id | multi_select ids[] | user id | catalog uid | tree uid | etc. Endpoint: GET /company/custom-properties.
Inputs: verbosity.
kaiten_list_custom_property_select_valuesList Custom Property Select ValuesARead-onlyIdempotent
Get the valid select / multi_select values for a custom property. Use this BEFORE writing the properties map via kaiten_update_card for any select / multi_select field — passing arbitrary integers will either fail or silently misassign. propertyId comes from kaiten_list_custom_properties (filter results by type='select' or type='multi_select'). Returns id, value (the display label), color, sort_order, condition. IMPORTANT: if the property exists but is not a select-type, the endpoint returns an empty array (not 400), so check the property type first. 404 means the propertyId is not in your company.
Inputs: propertyId (required), verbosity.
kaiten_list_filesList FilesARead-onlyIdempotent
List card attachments. fileId for kaiten_delete_file; cardId from kaiten_search_cards or kaiten_get_card. NOTE: mime_type is inferred from filename extension client-side because Kaiten does not persist the multipart Content-Type header. Unknown extensions return mime_type: null.
Inputs: cardId (required), verbosity.
kaiten_list_lanesList LanesARead-onlyIdempotent
Swimlanes for a board. Optional laneId on kaiten_create_card and kaiten_update_card when the board uses lanes. NOTE: the default lane often has an empty title — refer to it by lowest sort_order if you need to identify it. boardId from kaiten_list_boards.
Inputs: boardId (required), verbosity.
kaiten_list_spacesList SpacesARead-onlyIdempotent
List spaces visible to current user. Typical drill-down: kaiten_get_space for detail, kaiten_list_boards(spaceId) for the boards in a space, kaiten_list_space_users(spaceId) for members. Space IDs also feed kaiten_search_cards, kaiten_create_card, and kaiten_list_custom_properties.
Inputs: verbosity.
kaiten_list_space_usersList Space UsersARead-onlyIdempotent
Members of a space. Use to find user IDs for kaiten_update_card.ownerId or kaiten_create_card.ownerId when the target user isn't the API caller. spaceId from kaiten_list_spaces.
Inputs: spaceId (required), verbosity.
kaiten_list_sprintsList SprintsARead-onlyIdempotent
List company sprints with an optional active-flag filter. A sprint in Kaiten is a scrum-style time-box with velocity/committed tracking. Not every workspace uses sprints — an empty array means sprints are simply not configured here, not that your access is broken. Returns id, title, active, dates, velocity. Requires access to the company entities tree (403 otherwise). Use kaiten_get_sprint for the full per-sprint summary including cards.
Inputs: limit, active, offset, verbosity.
kaiten_list_subcolumnsList SubcolumnsARead-onlyIdempotent
List subcolumns of a parent column. Subcolumns split a column into vertical lanes (e.g. 'In Progress' → 'Implementation' / 'Review'). Each subcolumn has column_id set to the parent at verbosity=max. Returns standard column shape via simplifyColumn. Empty array if the column has no subcolumns — most boards don't use them. columnId from kaiten_list_columns.
Inputs: columnId (required), verbosity.
kaiten_list_subtasksList SubtasksARead-onlyIdempotent
List child cards linked to a parent card. cardId is the PARENT card; the tool returns its CHILD cards. Add new children: kaiten_create_card + kaiten_attach_subtask. An alternative is kaiten_get_card(cardId, includeChildren=true), which embeds the children inline.
Inputs: cardId (required), verbosity.
kaiten_list_usersList UsersARead-onlyIdempotent
Returns the full company user list — no pagination and no server-side filtering, suitable for small workspaces only. IDs feed kaiten_search_cards filters, kaiten_create_card.ownerId and kaiten_update_card.ownerId. If /users is denied on the current token, fall back to kaiten_get_current_user as a single-user source.
Inputs: verbosity.
kaiten_list_workspace_tagsList Workspace TagsARead-onlyIdempotent
List ALL tags in the workspace (across all cards). For tags on a specific card, use kaiten_list_card_tags. tagId for kaiten_remove_tag. Tags auto-create when added to a card via kaiten_add_tag.
Inputs: limit, query, offset, spaceId, +1 more.
kaiten_release_card_blockerRelease Card BlockerAIdempotent
Release a blocker on a card. Despite using DELETE under the hood, this does NOT remove the row — Kaiten flips released:true / released_by_id and keeps the blocker in history. The released blocker continues to appear in kaiten_list_card_blockers. To filter active vs released, check the released field client-side. There is no hard-delete API for blockers in Kaiten. Preflight verifies the blocker belongs to this card. blockerId from kaiten_list_card_blockers.
Inputs: cardId (required), blockerId (required).
kaiten_remove_card_external_linkRemove Card External LinkADestructive
Remove an external link from a card permanently. Unlike blockers (where DELETE is a soft release), this is a true hard-delete — the link disappears from kaiten_list_card_external_links afterwards. Preflight verifies the cardId+linkId pair matches before deletion, to prevent silent cross-card removal. linkId from kaiten_list_card_external_links.
Inputs: cardId (required), linkId (required).
kaiten_remove_card_memberRemove Card MemberADestructive
Detach a user from a card. WARNING: Kaiten resolves the member by userId alone — this preflight verifies the user is actually a member of this specific card before deleting. cardId from kaiten_search_cards; userId from kaiten_list_card_members. Returns: the removed userId.
Inputs: cardId (required), userId (required).
kaiten_remove_tagRemove Card TagADestructive
Remove a tag from a card. WARNING: Kaiten returns success even when tagId does not belong to the card (or doesn't exist at all). Verify the tag is actually attached via kaiten_list_card_tags before relying on the success message. tagId from kaiten_list_card_tags or kaiten_add_tag.
Inputs: tagId (required), cardId (required).
kaiten_rename_checklistRename ChecklistAIdempotent
Rename a checklist. cardId and checklistId from kaiten_get_checklist. The only field supported is name; items are managed via the *_checklist_item tools.
Inputs: name (required), cardId (required), checklistId (required), verbosity.
kaiten_search_cardsSearch CardsARead-onlyIdempotent
Search cards with filters and pagination. Pass boardId (from kaiten_list_boards) or spaceId (from kaiten_list_spaces) to limit scope. The query parameter performs a substring match against card titles (server searches the title field only). The condition parameter accepts only 1=live (default) or 2=archived — Kaiten has no 'all' filter. To list live + archived together, omit condition (defaults to live) and call again with condition: 2. Use kaiten_get_card for full detail on a specific card. Returns: array of cards (simplified per verbosity).
Inputs: asap, limit, query, state, +27 more.
kaiten_set_card_responsibleSet Card Responsible MemberAIdempotent
Promote an existing card member to type=2 (responsible). Kaiten's API only accepts type:2 on this endpoint — there is no 'unset responsible' call (demote via kaiten_remove_card_member then re-add with kaiten_add_card_member). The user must already be a member; call kaiten_add_card_member first if needed. userId from kaiten_list_card_members. Returns: the updated user.
Inputs: cardId (required), userId (required), verbosity.
kaiten_update_cardUpdate CardAIdempotent
Update card fields. For moves use kaiten_list_columns, kaiten_list_lanes, kaiten_list_boards IDs. To change state — move the card via columnId (Kaiten state is computed from column.type, not settable directly). To change size — use sizeText (the numeric size field on a card is read-only). Set custom property values via the properties map (see kaiten_list_custom_properties for IDs and types). NOTE: response in min/normal verbosity may show board_title:null and column_title:null because PATCH /cards/{id} returns a flat payload. Re-fetch via kaiten_get_card to populate, or use verbosity=raw.
Inputs: cardId (required), asap, size, state, +13 more.
kaiten_update_card_blockerUpdate Card BlockerAIdempotent
Patch an existing blocker. Updatable fields: reason, blockerCardId, dueDate, dueDateTimePresent. Cannot set released — that's a separate endpoint, use kaiten_release_card_blocker. Cannot un-release — once released:true, no API path back to released:false. Preflight verifies the blocker belongs to this card. blockerId from kaiten_list_card_blockers.
Inputs: cardId (required), blockerId (required), reason, dueDate, +3 more.
kaiten_update_card_external_linkUpdate Card External LinkAIdempotent
Update url or description of an existing card external link. At least one of url / description must be provided (empty PATCH rejected before the API call). description accepts null to clear the label. linkId belongs to a specific card — use kaiten_list_card_external_links to discover ids. Preflight verifies the link belongs to the given card before PATCHing, to prevent silent cross-card mutation.
Inputs: cardId (required), linkId (required), url, verbosity, +1 more.
kaiten_update_checklist_itemUpdate Checklist ItemAIdempotent
Update a checklist item's text or checked flag. text has a 4096-character limit (Kaiten server-side cap). Item supports text and checked state only — due_date and responsible_id are not exposed by this fork. itemId from kaiten_get_checklist.
Inputs: cardId (required), itemId (required), checklistId (required), text, +2 more.
kaiten_update_commentUpdate CommentAIdempotent
Replace the body of an existing comment. Markdown by default — if you are sending HTML, also pass textFormat: 'html'. QUIRK: Kaiten's comment markdown does NOT support ATX headings (### Header renders as literal text). Use bold or switch to HTML if you need a heading inside a comment. Resolve commentId via kaiten_get_card_comments. The cardId is part of the URL path — both cardId and commentId must reference the actual card-comment pair (mismatched pair returns 500 from Kaiten). Returns: the updated comment object.
Inputs: cardId (required), commentId (required), text, verbosity, +1 more.
kaiten_update_timelogUpdate TimelogAIdempotent
Patch a timelog (timeSpentMinutes is in minutes). logId and cardId from kaiten_get_card_timelogs or kaiten_get_user_timelogs.
Inputs: logId (required), cardId (required), roleId, comment, +3 more.
kaiten_upload_fileUpload FileA
Upload file attachment (base64). Verify with kaiten_list_files. Prefer description links for large files. Note: Kaiten does not persist the multipart Content-Type — mime_type in responses is inferred from the file extension. contentBase64 is decoded leniently — empty strings and garbage produce 0-byte uploads silently. Validate before calling.
Inputs: cardId (required), fileName (required), contentBase64 (required), verbosity, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 63 tools
Every tool maps to a distinct resource-action pair, and the few potentially overlapping tools (search_cards vs get_space_cards/get_board_cards, list_card_tags vs list_workspace_tags) are explicitly cross-referenced and disambiguated in their descriptions. The descriptions consistently tell the agent where IDs come from and which alternate tool to use, so misselection risk is low.
All tool names follow a kaiten_<verb>_<noun> snake_case pattern with predictable verbs like get, list, create, update, delete, add, and remove. The main deviation is mixing get and list for collection-style tools (get_card_comments, get_space_cards, get_user_timelogs vs list_boards, list_spaces), plus a few one-off verbs like release and attach, but the overall pattern remains readable and consistent.
63 tools is far beyond the 25+ threshold and creates a heavy tool surface for an agent to navigate, even though the domain is broad. Several tools could be consolidated or exposed through verbosity options (e.g. get_space_cards/get_board_cards vs search_cards, get_card includeChildren vs list_subtasks), so the count feels over-scoped rather than well-trimmed.
The server provides thorough lifecycle coverage for cards, comments, timelogs, checklists, tags, files, members, blockers, external links, and sprints, including create/read/update/delete where the API supports it. Minor gaps exist: no board/space creation or administration, no explicit archive/unarchive card tool, and no global tag deletion or custom property management, but most workflows complete without dead ends.
Maintenance
Related MCP Connectors
Remote MCP for Kanban AI boards—manage projects, tasks, and comments from AI tools.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Task & board management for AI agents + humans. Kanban, comments, digests via MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server for integrating Kaiten API with Claude Desktop, enabling management of cards, comments, spaces, and boards with advanced features like verbosity control, response format selection, and auto-truncation.33MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for interacting with Kaiten project management through its REST API. Enables managing spaces, boards, cards, comments, checklists, tags, and time logs.1MIT
- AlicenseNot gradedqualityDmaintenanceMCP server and CLI tool for interacting with Kaiten project management API, optimized for token efficiency. Enables AI assistants to search, create, update, and manage tasks with minimal token usage.61 npmMIT
- FlicenseCqualityCmaintenanceEnables interaction with Kaiten project management platform through 246 tools for managing cards, comments, time logs, boards, and more.2466-