Skip to main content
Glama

kaiten-mcp

npm version License: MIT

Русский

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.


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

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)

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

Available Tools

63 tools
kaiten_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_memberAdd Card MemberA
Idempotent

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 TagA
Idempotent

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 SubtaskA
Idempotent

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 CardA
Destructive

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 ChecklistA
Destructive

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 ItemA
Destructive

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 CommentA
Destructive

Delete comment. commentId and cardId from kaiten_get_card_comments.

Inputs: cardId (required), commentId (required).

kaiten_delete_fileDelete FileA
DestructiveIdempotent

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 TimelogA
Destructive

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 SubtaskA
Idempotent

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 BoardA
Read-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 CardsA
Read-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 CardA
Read-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 CommentsA
Read-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 HistoryA
Read-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 TimelogsA
Read-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 ChecklistA
Read-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 UserA
Read-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 SpaceA
Read-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 CardsA
Read-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 SummaryA
Read-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 TimesheetA
Read-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 TimelogsA
Read-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 BoardsA
Read-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 BlockersA
Read-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_membersList Card MembersA
Read-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 TagsA
Read-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 TypesA
Read-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 ColumnsA
Read-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 RolesA
Read-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 PropertiesA
Read-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 ValuesA
Read-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 FilesA
Read-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 LanesA
Read-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 SpacesA
Read-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 UsersA
Read-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 SprintsA
Read-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 SubcolumnsA
Read-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 SubtasksA
Read-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 UsersA
Read-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 TagsA
Read-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 BlockerA
Idempotent

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_memberRemove Card MemberA
Destructive

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 TagA
Destructive

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 ChecklistA
Idempotent

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 CardsA
Read-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 MemberA
Idempotent

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 CardA
Idempotent

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 BlockerA
Idempotent

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_checklist_itemUpdate Checklist ItemA
Idempotent

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 CommentA
Idempotent

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 TimelogA
Idempotent

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

    A3.9/5.0

    Scored across 63 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP 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.
      33
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for interacting with Kaiten project management through its REST API. Enables managing spaces, boards, cards, comments, checklists, tags, and time logs.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP 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 npm
      MIT