Content
-mcp
<!-- mcp-name: io.github.evvfebruary/kaiten**MCP server for [Kaiten](https://kaiten.ru/)** — integration of Kaiten kanban boards and tasks with AI assistants ([Cursor](https://cursor.com/), [Claude Code](https://docs.anthropic.com/en/docs/claude-code) MCP client).
Manage cards directly from chat: create tasks, move them across columns, update descriptions, leave comments and tags — without manual copying from the web interface and without huge JSON responses from the API in the.
## Why is it needed
- Connect **Kait Cursor / Claude Code** via [Model Context Protocol](https://protocol.io/)
- Work with spaces, boards, columns and cards using voice commands
- Save tokens: responses are compact by default (des on request)
- Deploy locally (stdio) or for a team (Streamable HTTP / Docker / Kubernetes)
## Capabilities
- Local transport **stdio** for Cursor and Claude Code
- Remote **Streamable HTTP** (`POST /mcp`) for team hosting
- for each request (credentials are not saved to disk)
-: page size 20 by default (max 100), without attachments and "noisy" nested fields
- Benchmarks of payload size (`kaiten-mcp-benchmark`) to prevent response inflation over time
- Structured logs in stderr (safe for stdio MCP)
## Quick Start
### Requirements
- Python 3.12+
- [uv](https://docs.astral.sh/uv/)
- Kaiten API token (Profile → API key in your instance, e.g., `https://<company>.kaiten.ru/profile/api-key`)
### 1. Installation and Launch
```bash
export KAITEN_API_TOKEN='your-token'
export KAITEN_WORKSPACE_SLUG-company' # → https://your-company.kaiten.ru1
uvx kaiten-mcp --transport stdio
```
`uvx` downloads the package from PyPI, creates an, and launches the server.
Cloning the repository is not required.
For on-prem/custom domain, specify the full API root instead of the slug:
```bash
export KAIT='https://kaiten.example.com/api'
```
Other variables are in [`.env.example.example).
###. Cursor
: [`.cursor/mcp.jsoncursor/mcp.json).
1. Export the workspace to the environment that inherits Cursor:
```bash
AITEN_API_TOKEN='your-token'
exportEN_WORKSPACE_SLyour-company'
```
Restart Cursor after changing environment variables.
3. Open **Output → MCP Logs** and ensure thatkaiten` server has connected.
4 the agent: "" or "find tasks on board …".
`${env:KAITEN_API_TOKEN}` and `${env:KAITEN_WORK}` are substituted by Cursor. Do not tokens.
### 3. Claude Code
Project`.mcp.json`](.mcp```bash
export KAITEN_API_TOKEN='your-token'
export KAITEN_WORKSPACE_SLUG'
claude mcp list
```
:
```bash
claude mcp add stdio kaiten -- uv run kaiten-mcp --transport stdio
```
## Examples of requests to the agent
- "Show all spaces in Kaiten"
- "Find boards in space X and create a card 'Fix login bug'"
- "Move task #1234 to the In Progress column"
- "Add a comment #1234: ready for review"
Add the 'hotfix' tag to task4"
Typical tool order:
1.` → `list_boards` → `list_columns` / `list_lanes`
2._task` / `list_tasks` / `` / `update_task` / `move. `add_comment` / `add_tag` if necessary
## MCP Tools
| Tool |
|------|--------|
| `list_spaces List of spaces (id, title) |
|_boards` | Boards of a space |
| `list | Columns of a board |
| `list_lanes` | Lanes of a board |
| `create_task` | card (`title` + `board_id`) |
| `` | Task details (`include_description` — on request) `list_tasks` | Filtered compact list (query, board, tag, …| `update_task` fields (title, description, condition, …) `move_task` | Move (board / column / lane) |
| `add / `list_comments` | Comments |
| `list_tags` / `get_task_tags` |
| `add_tag` | Add a tag** |
| `_from_task` | Remove a tag **by id** |
## Remote Server / Docker / Kubernetes
Streamable HTTP:
```bash
uv run kaiten-mtransport streamable-http --host 0.0.0.0 --port 8000- Health: `GET /`
- MCP: /mcp`
Dockerbash
docker pull gh/evvfebruary/kaitcp:latest
docker run --p 80000 \
-e KAITEN_WORKSPACE_SLUG=your-company \
ghcrvfebruary/kaiten:latest
```
To build the image locally, run `docker build -t kaiten-mcp .`.
Each client passes its own```http
Authorization: Bearer <kaiten-apiExample configurations:
-/remote-mcp/ccp.json`](examples/cp/cursor.mcp.json)
examples/cp/claude.mcp.json`](examples/remote-mcp/claude.mcp.json)
Notes for Kubernetes:
- Stateless replicas are allowed (`stateless_http=True`)
- TLS — on Ingress
- Increase proxy/read timeouts for streaming
- Do not log the `Authorization` header
- Kaiten has a limit of ~50 req/s — divide the budget amongThe Bearer token model is a deliberate choice for vnot browser OAuth).
Variables
| Variable | Description |
|----------|-----------|-------------|
| `KAITEN_API_TOKEN` | Yes (stdio) | API token; for HTTP — also in `Authorization: Bearer` |
| `KA_WORKSPACE_SLUG` | Yes\* | Slug: `` → `https://acme.kaiten.ru1` |
| `KAITEN_BASE_URL` | Yes\* | Full API root (on-prem); takes priority over slug |
| `KAITEN_HOST` / `KAITEN_PORT` | No | Bind for HTTP (default `127.0.0.1:8000`) |
| `KAITEN_LOG_LEVEL` | No | `DEBUG` \| `INFO` \| `WARNING` \| `ERROR| `KAITEN` | No | `text` \| `json` |
| `KAITEN_LOGIES` | No |acted previews in logsKAITEN_ENABLE_METRICS` | No | Payload without secrets |
\* EitherITEN_WORKSPACE_SLUG` or `KAITEN_BASE_URL` is required.
## Token Savings
- Default list page size: **20** (max **100**)
- No descriptions, attachments, or deep duplicates in lists
- Mutations return id/url and changed fields
- Explicit truncation: `truncated`, `next_offset`, `has_more`
- Short tool descriptions
Response size budget checks:
```bash
uv run kaiten-mcp-benchmark
uv run kaiten-mcp-benchmark --check
```
## Logging
Logs always go to **stderr** (compatible with stdio MCP).
```bash
export KAITEN_LOG_LEVEL=INFO
export KAITEN_LOG_FORMAT=json
uv run kaiten-mcp --transport stdio --log-format json
```
Useful events: `server_starting`, `tool_start` / `tool_success` / `tool_error`,aiten_request`, `kaiten_rate_limited`.
Secrets are edited; tokens are visible only as fingerprints like `token_fp=len=40:…ab12`.
## Development
```bash
uv sync --all-groups
uv run ruff format .
uv run ruff check .
uv run ty check
uv run pytest
uv run kaiten-mcp-benchmark --check
```
Live smoke (optional, not in CI by default):
```bash
KAITEN_API_TOKEN=... KAITEN_WORKSPACE_SLUG=... uv run pytest -m live
```
Release publication (PyPI, GHCR, Official MCP Registry) is described in [RELEASING.md](RELEASING.md).
## Structure
```text
src/kaiten_mcp/
api/ # HTTP client and endpoint adapters
tools/ # MCP tools
auth.py # Token per request
config.py # Settings
presentation.py
metrics.py
server.py
__main__.py
tests/
benchmarks/
examples/remote-mcp/
server.json # Official MCP Registry metadata
RELEASING.md
```
## Security
- Token is taken from HTTP Bearer or `KAITEN_API_TOKEN` for each request
- Server does not write tokens to disk
- Prefer environment variables over hardcoding in MCP JSON
- Rights on Kaiten side are determined by the caller's token
## FAQ
**How to connect Kait Cursor?**
Install dependencies via `uv`, setITEN_API_TOKEN` and `KAITEN_WORKUG`, and restart Cursor — configuration is already in [/mcp.json`](.cursor/mcp.json).
**Where Kaiten API token?**
In your instance → API key (`https://<company>.kaiten.ru/profile/api-key`). OAuth is not used for this scenarioHow does this server differ from other kaiten-mcp?**
Focus on **compact responses** and model context savings, remote Streamable HTTP for teams without storing tokens on the server.
**Can I deploy for the whole team?**
Yes: Docker / Kubernetes with `streamable-http`; each employee
