mcp-kaiten

Русский | 中文

Why mcp-kaiten exists

MCP server for Kaiten — cards, time-logs, boards, comments, users.

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

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

Quick Start

1. Get API Token

Go to your Kaiten instance (e.g. https://your-domain.kaiten.ru)
Open Profile → API Key
Create a new token and copy it

2. Add to Cursor / MCP Client

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

The server starts automatically when the MCP client connects.

What Can It Do?

Cards

Tool	Description
`kaiten_get_card`	Get card by ID (with optional children)
`kaiten_search_cards`	Search cards with filters, dates, pagination
`kaiten_get_space_cards`	Get cards in a space
`kaiten_get_board_cards`	Get cards on a board
`kaiten_create_card`	Create a new card
`kaiten_update_card`	Update card fields, move between columns/boards
`kaiten_delete_card`	Delete a card

Comments

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

Tool	Description
`kaiten_get_user_timelogs`	Get time-logs for a user in a date range
`kaiten_get_card_timelogs`	Get 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`)

Spaces & Boards

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
`kaiten_list_columns`	List columns (statuses) of a board
`kaiten_list_lanes`	List lanes (swimlanes) of a board
`kaiten_list_card_types`	List card types of a board

Subtasks

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

Checklists

Tool	Description
`kaiten_get_checklists`	Get checklists for a card
`kaiten_create_checklist`	Create a new checklist
`kaiten_delete_checklist`	Delete a checklist
`kaiten_add_checklist_item`	Add an item to a checklist
`kaiten_update_checklist_item`	Update a checklist item

Attachments

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

Tool	Description
`kaiten_list_custom_properties`	List custom properties for a space

Users

Tool	Description
`kaiten_get_current_user`	Get the authenticated user
`kaiten_list_users`	List all users
`kaiten_get_user_roles`	Get roles of the current user

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`	Generate time tracking report for a date range
`board-overview`	Summarize board: columns, cards, overdue items

Authentication

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

Go to your Kaiten profile → API Key
Create and copy the token
Set KAITEN_API_TOKEN in MCP config

Environment Variables

Variable	Required	Description
`KAITEN_API_TOKEN`	yes	API token (Bearer)
`KAITEN_URL`	yes	Kaiten instance URL (e.g. `https://your-domain.kaiten.ru`)
`KAITEN_DEFAULT_SPACE_ID`	no	Default space ID for card search (if `spaceId` is not specified)
`KAITEN_ALLOWED_SPACE_IDS`	no	Comma-separated space IDs to restrict access
`KAITEN_ALLOWED_BOARD_IDS`	no	Comma-separated board IDs to restrict access

Verbosity

Every tool accepts an optional verbosity parameter (default: min) to control response size. Use min for compact responses that save LLM context, normal for common fields, max for full detail, or raw for the unprocessed API response.

Reliability

Automatic retries: failed requests (429, 5xx, network errors, timeouts) are retried up to 3 times with exponential backoff.
Idempotency: write requests include idempotency keys to prevent duplicate mutations on retries.
Caching: reference data (spaces, boards, users, roles) is cached with automatic background refresh.
Response optimization: compact JSON, automatic truncation of large responses, verbosity control.
Crash protection: unhandled errors are logged without crashing the server.
Actionable errors: error messages include hints on what to do next.

Troubleshooting

Server won't start: check that KAITEN_API_TOKEN and KAITEN_URL are set in the MCP config env block.
401 errors: token may be expired or invalid. Generate a new one in Kaiten profile.
Large responses: use filters (boardId, spaceId) or lower limit to reduce response size.

Changelog

License

Tool	Description
`kaiten_list_tags`	List all workspace tags
`kaiten_add_tag`	Add a tag to a card
`kaiten_remove_tag`	Remove a tag from a card

mcp-kaiten

Quick Install

mcp-kaiten

Quick Start

1. Get API Token

2. Add to Cursor / MCP Client

What Can It Do?

Cards

Comments

Time Logs

Spaces & Boards

Subtasks

Tags

Checklists

Attachments

Custom Fields

Users

Resources

Prompts

Authentication

Environment Variables

Verbosity

Reliability

Troubleshooting

Reviews