kaiten-mcp

MCP-сервер для Kaiten — интеграция канбан-досок и задач Kaiten с AI-ассистентами (Cursor, Claude Code и любым MCP-клиентом).

Управляйте карточками прямо из чата: создавайте задачи, перемещайте по колонкам, обновляйте описания, оставляйте комментарии и теги — без ручного копирования из веб-интерфейса и без огромных JSON-ответов API в контексте модели.

Зачем это нужно

Подключить Kaiten к Cursor / Claude Code через Model Context Protocol
Работать с пространствами, досками, колонками и карточками голосом агента
Экономить токены: ответы компактные по умолчанию (описания — только по запросу)
Развернуть локально (stdio) или для команды (Streamable HTTP / Docker / Kubernetes)

Возможности

Локальный транспорт stdio для Cursor и Claude Code
Удалённый Streamable HTTP (POST /mcp) для командного хостинга
Токен Kaiten на каждый запрос (credentials не сохраняются на диске)
Компактные списки: страница по умолчанию 20 (макс. 100), без вложений и «шумных» вложенных полей
Бенчмарки размера payload (kaiten-mcp-benchmark), чтобы ответы не раздувались со временем
Структурированные логи в stderr (безопасно для stdio MCP)

Быстрый старт

Требования

Python 3.12+
uv
API-токен Kaiten (Профиль → API-ключ в вашем инстансе, например https://<компания>.kaiten.ru/profile/api-key)

1. Установка и запуск

export KAITEN_API_TOKEN='ваш-токен'
export KAITEN_WORKSPACE_SLUG='ваша-компания'   # → https://ваша-компания.kaiten.ru/api/v1

uvx kaiten-mcp --transport stdio

uvx скачивает пакет из PyPI, создаёт изолированное окружение и запускает сервер. Клонировать репозиторий не требуется.

Для on-prem / кастомного домена вместо slug задайте полный корень API:

export KAITEN_BASE_URL='https://kaiten.example.com/api/v1'

Остальные переменные — в .env.example.

2. Cursor

Конфиг проекта уже есть: .cursor/mcp.json.

Экспортируйте токен и workspace в окружение, которое наследует Cursor:

export KAITEN_API_TOKEN='ваш-токен'
export KAITEN_WORKSPACE_SLUG='ваша-компания'

Перезапустите Cursor после смены переменных окружения.
Откройте Output → MCP Logs и убедитесь, что сервер kaiten подключился.
Попросите агента: «покажи пространства» или «найди задачи на доске …».

${env:KAITEN_API_TOKEN} и ${env:KAITEN_WORKSPACE_SLUG} подставляет Cursor. Не коммитьте реальные токены.

3. Claude Code

Конфиг проекта: .mcp.json.

export KAITEN_API_TOKEN='ваш-токен'
export KAITEN_WORKSPACE_SLUG='ваша-компания'
claude mcp list

Или вручную:

claude mcp add --transport stdio kaiten -- uv run kaiten-mcp --transport stdio

Примеры запросов к агенту

«Покажи все пространства в Kaiten»
«Найди доски в пространстве X и создай карточку „Исправить баг логина“»
«Перенеси задачу #1234 в колонку In Progress»
«Добавь комментарий к карточке #1234: готово к ревью»
«Повесь тег „hotfix“ на задачу #1234»

Типовой порядок инструментов:

list_spaces → list_boards → list_columns / list_lanes
create_task / list_tasks / get_task / update_task / move_task
add_comment / add_tag_to_task при необходимости

Инструменты MCP

Инструмент	Назначение
`list_spaces`	Список пространств (id, title)
`list_boards`	Доски пространства
`list_columns`	Колонки доски
`list_lanes`	Дорожки доски
`create_task`	Создать карточку (`title` + `board_id`)
`get_task`	Детали задачи (`include_description` — по запросу)
`list_tasks`	Фильтрованный компактный список (query, board, column, tag, …)
`update_task`	Обновление полей (title, description, owner, condition, …)
`move_task`	Перемещение (board / column / lane / sort)
`add_comment` / `list_comments`	Комментарии
`list_tags` / `get_task_tags`	Теги
`add_tag_to_task`	Добавить тег по имени
`remove_tag_from_task`	Снять тег по id

Удалённый сервер / Docker / Kubernetes

Streamable HTTP:

uv run kaiten-mcp --transport streamable-http --host 0.0.0.0 --port 8000

Health: GET /healthz
MCP: POST /mcp

Docker:

docker pull ghcr.io/evvfebruary/kaiten-mcp:latest
docker run --rm -p 8000:8000 \
  -e KAITEN_WORKSPACE_SLUG=ваша-компания \
  ghcr.io/evvfebruary/kaiten-mcp:latest

Для локальной разработки образ можно собрать командой docker build -t kaiten-mcp ..

Каждый клиент передаёт свой токен:

Authorization: Bearer <kaiten-api-token>

Примеры конфигов:

Заметки для Kubernetes:

Stateless-реплики допустимы (stateless_http=True)
TLS — на Ingress
Увеличьте proxy/read timeouts для streaming
Не логируйте заголовок Authorization
У Kaiten лимит порядка ~50 req/s — делите бюджет между репликами

Модель с Bearer-токеном на запрос — осознанный выбор v1 (не browser OAuth).

Переменные окружения

Переменная	Обязательна	Описание
`KAITEN_API_TOKEN`	Да (stdio)	API-токен; для HTTP — также в `Authorization: Bearer`
`KAITEN_WORKSPACE_SLUG`	Да*	Slug: `acme` → `https://acme.kaiten.ru/api/v1`
`KAITEN_BASE_URL`	Да*	Полный корень API (on-prem); имеет приоритет над slug
`KAITEN_HOST` / `KAITEN_PORT`	Нет	Bind для HTTP (по умолчанию `127.0.0.1:8000`)
`KAITEN_LOG_LEVEL`	Нет	`DEBUG` \| `INFO` \| `WARNING` \| `ERROR`
`KAITEN_LOG_FORMAT`	Нет	`text` \| `json`
`KAITEN_LOG_BODIES`	Нет	Компактные redacted-превью в логах
`KAITEN_ENABLE_METRICS`	Нет	Метрики размера payload без секретов

* Нужен либо KAITEN_WORKSPACE_SLUG, либо KAITEN_BASE_URL.

Экономия токенов

Размер страницы списка по умолчанию: 20 (макс. 100)
В списках нет описаний, вложений и глубоких дублей
Мутации возвращают id/url и изменённые поля
Обрезка явная: truncated, next_offset, has_more
Коротко описанные схемы инструментов

Проверка бюджетов размера ответа:

uv run kaiten-mcp-benchmark
uv run kaiten-mcp-benchmark --check

Логирование

Логи всегда идут в stderr (совместимо со stdio MCP).

export KAITEN_LOG_LEVEL=INFO
export KAITEN_LOG_FORMAT=json
uv run kaiten-mcp --transport stdio --log-format json

Полезные события: server_starting, tool_start / tool_success / tool_error, kaiten_request, kaiten_rate_limited.

Секреты редактируются; токены видны только как fingerprint вида token_fp=len=40:…ab12.

Разработка

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 (опционально, не в CI по умолчанию):

KAITEN_API_TOKEN=... KAITEN_WORKSPACE_SLUG=... uv run pytest -m live

Публикация релизов (PyPI, GHCR, Official MCP Registry) описана в RELEASING.md.

Структура

src/kaiten_mcp/
  api/           # HTTP-клиент и адаптеры эндпоинтов
  tools/         # MCP-инструменты
  auth.py        # Токен на запрос
  config.py      # Настройки
  presentation.py
  metrics.py
  server.py
  __main__.py
tests/
benchmarks/
examples/remote-mcp/
server.json      # Official MCP Registry metadata
RELEASING.md

Безопасность

Токен берётся из HTTP Bearer или KAITEN_API_TOKEN на каждый запрос
Сервер не пишет токены на диск
Предпочитайте переменные окружения, а не хардкод в MCP JSON
Права на стороне Kaiten определяются токеном вызывающего

FAQ

Как подключить Kaiten к Cursor?
Установите зависимости через uv, задайте KAITEN_API_TOKEN и KAITEN_WORKSPACE_SLUG, перезапустите Cursor — конфиг уже в .cursor/mcp.json.

Где взять API-токен Kaiten?
В вашем инстансе: Профиль → API-ключ (https://<компания>.kaiten.ru/profile/api-key). OAuth у публичного API Kaiten для этого сценария не используется.

Чем этот сервер отличается от других kaiten-mcp?
Фокус на компактных ответах и экономии контекста модели, плюс готовый remote Streamable HTTP для команды без хранения токенов на сервере.

Можно ли развернуть для всей команды?
Да: Docker / Kubernetes с streamable-http; каждый сотрудник передаёт свой Bearer-токен в заголовке.

Работает ли с on-prem Kaiten?
Да — задайте KAITEN_BASE_URL на ваш /api/v1.

Лицензия

MIT