Kaiten

kaiten-mcp

Русский | English

MCP-сервер для [Kaiten](https://kaiten.ru/) — интеграция канбан-досок и задач 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. Для использования в другом проекте добавьте сервер в его .cursor/mcp.json, сохранив существующие записи:

{

"mcpServers": { "kaiten": { "command": "uvx", "args": ["kaiten-mcp", "--transport", "stdio"], "env": { "KAITEN_API_TOKEN": "${env:KAITEN_API_TOKEN}", "KAITEN_WORKSPACE_SLUG": "${env:KAITEN_WORKSPACE_SLUG}" } } } }

Этот вариант устанавливает пакет из PyPI и не требует клонирования репозитория. uvx должен быть доступен в PATH процесса Cursor. Для on-prem замените запись workspace slug на "KAITEN_BASE_URL": "${env:KAITEN_BASE_URL}" и экспортируйте полный корень API.

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

export KAITEN_API_TOKEN='ваш-токен'

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

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

${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 -- uvx kaiten-mcp --transport stdio

Skill для работы с Kaiten

MCP-сервер предоставляет инструменты и доступ к Kaiten. Бесплатный skill подсказывает агенту, как находить и изменять карточки, готовить задачи, делать обзор доски и предлагать улучшения очереди. Установка skill не подключает сервер: сначала настройте MCP.

Сохраните файл skill в .cursor/skills/kaiten/SKILL.md своего проекта. Или скопируйте его из локального клона этого репозитория:

mkdir -p /path/to/your-project/.cursor/skills/kaiten

cp skills/kaiten/SKILL.md /path/to/your-project/.cursor/skills/kaiten/SKILL.md

Замените /path/to/your-project на путь своего проекта; перед заменой существующего skill проверьте его содержимое. Начните новый Agent-чат и убедитесь, что skill доступен. Cursor может выбирать его для запросов о Kaiten; подробности — в документации Cursor. Для другого клиента с поддержкой skills используйте его каталог установки. Инструкции написаны на английском, но агент отвечает на языке пользователя.

Примеры менеджерских запросов:

• «Сделай обзор доски Product по колонкам и дай ссылки на задачи, требующие внимания».
• «Посмотри очередь Product и предложи, какие описания стоит уточнить. Карточки пока не меняй».
• «Подготовь задачу с критериями готовности на основе этих требований: …».

Обзор отражает доступное текущее состояние доски. Инструменты не предоставляют полной истории для расчёта throughput за неделю или cycle time.

Демонстрация

Сценарий записи в Cursor: создать карточку → переместить → получить обзор демонстрационных задач. Тестовый стенд подготовлен; реальная запись в Cursor ещё не выполнена. Подготовка стенда и проверки.

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

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

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

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

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

Удалённый сервер / 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>

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

• examples/remote-mcp/cursor.mcp.json
• examples/remote-mcp/claude.mcp.json

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

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

HTTP всегда требует Bearer-токен вызывающего; общий KAITEN_API_TOKEN используется только в stdio. Полноценная MCP OAuth-авторизация пока не реализована.

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

\* Нужен либо 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

Проверки совместимости (все 15 инструментов, оба транспорта, документация API):

uv run kaiten-mcp-check offline

uv run kaiten-mcp-check docs

После настройки выделенной тестовой доски:

uv run kaiten-mcp-check live

Настройка стенда, ежедневного CI и обновление эталонов — CHECKING.md. 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-заголовка; для stdio — из 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