kaiten-mcp

MCP-сервер для полного управления Kaiten из любого MCP-клиента. Предоставляет 36 инструментов kaiten_*: пространства, доски, карточки, комментарии, чек-листы, учёт времени, теги, участники, гибкие выборки, планирование дня.

Два способа использования

(а) Локальный stdio-сервер через npm

Устанавливается как npm-пакет и запускается MCP-клиентом локально. Токен хранится в переменных окружения или запрашивается интерактивно (elicitation).

Подходит для: Cowork, Claude Code, Claude Desktop (локальный).

(б) Удалённый сервер на Vercel

Next.js-приложение из apps/web разворачивается на Vercel и становится удалённым MCP-сервером с OAuth 2.1 + PKCE. Каждый сотрудник подключается по URL в Claude Desktop и вводит свой Kaiten API-токен — без раздачи токенов через конфиги.

Подходит для: командного использования, Claude Desktop (удалённый connector).

Related MCP server: planka-mcp

Локальный stdio-сервер

Возможности

36 инструментов kaiten_*:

Планировочные инструменты

• kaiten_today_tasks — активные карточки пользователя со сроком на сегодня или раньше, отсортированные по приоритету и сроку.

• kaiten_overdue_cards — только просроченные карточки.

• kaiten_plan_day — готовый план дня: группировка «Просрочено / На сегодня» + markdown-текст и структурированный список.

Если user_id не указан — берётся текущий пользователь токена.

Требования

• Node.js >= 20 (рекомендуется 22 LTS, версия закреплена в mise.toml).

• Персональный API-токен Kaiten.

Установка

# Из npm (после публикации):
npm install -g kaiten-mcp

# Из исходников:
git clone <repo> kaiten-mcp
cd kaiten-mcp
npm install
npm run build

Конфигурация

Скопируйте packages/cli/.env.example в packages/cli/.env и заполните (или передайте переменные через конфиг MCP-клиента):

Где взять токен: в Kaiten откройте профиль → раздел с API-ключами и создайте токен.

Интерактивный запрос токена (elicitation)

* — KAITEN_API_URL и KAITEN_API_TOKEN не обязательны на старте. Если они не заданы, сервер запросит их у вас в самом клиенте при первом обращении к Kaiten — через стандартный механизм MCP elicitation. Введённые значения хранятся только в памяти процесса на время сессии и нигде не записываются на диск.

• Работает, только если клиент поддерживает elicitation (объявляет capability elicitation).

• Если клиент не поддерживает elicitation и переменные не заданы — при вызове любого инструмента вернётся понятная ошибка с просьбой задать переменные.

• Хотите всегда вводить токен вручную — просто не указывайте KAITEN_API_TOKEN.

Подключение в Cowork

{
  "mcpServers": {
    "kaiten": {
      "command": "node",
      "args": ["/absolute/path/to/kaiten-mcp/packages/cli/dist/index.js"],
      "env": {
        "KAITEN_API_URL": "https://your-domain.kaiten.ru/api/latest",
        "KAITEN_API_TOKEN": "ваш-токен"
      }
    }
  }
}

Блок env можно и не указывать — тогда при первом обращении к Kaiten сервер сам спросит токен прямо в Cowork (см. Интерактивный запрос токена).

Подключение в Claude Code

claude mcp add kaiten \
  --env KAITEN_API_URL=https://your-domain.kaiten.ru/api/latest \
  --env KAITEN_API_TOKEN=ваш-токен \
  -- node /absolute/path/to/kaiten-mcp/packages/cli/dist/index.js

Подключение в Claude Desktop (локально)

В claude_desktop_config.json добавьте тот же блок mcpServers, что и для Cowork выше.

Тесты (stdio)

npm run build
npm run smoke -w kaiten-mcp      # initialize + tools/list (без кредов)
npm run test:elicit -w kaiten-mcp # проверка интерактивного запроса токена
npm run test -w @kaiten-mcp/core  # unit-тесты ядра (vitest)

Удалённый сервер на Vercel

Приложение apps/web — это Next.js-сервер с полным OAuth 2.1 + PKCE флоу, который разворачивается на Vercel. Сотрудники подключают его в Claude Desktop по URL, а не через конфиги с токенами.

Важно: Claude Desktop поддерживает только OAuth-аутентификацию для удалённых connector-ов — передать токен через заголовок или URL-параметр нельзя. Именно поэтому здесь реализован полный OAuth-флоу.

Как это работает

1. Администратор деплоит apps/web на Vercel.

2. Сотрудник в Claude Desktop: Settings → Connectors → Add custom connector → вводит URL деплоя.

3. Claude Desktop запускает OAuth: открывает браузер, отображается форма — сотрудник вводит свой персональный Kaiten API-токен.

4. Токен шифруется через JWE (AUTH_SECRET) и возвращается Claude Desktop как Bearer-токен.

5. На каждый MCP-запрос сервер расшифровывает токен и обращается к Kaiten от имени конкретного сотрудника.

6. База данных не нужна — архитектура полностью stateless.

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

Скопируйте apps/web/.env.example в apps/web/.env.local и заполните для локальной разработки.

Деплой на Vercel

Рекомендуемый способ — Root Directory в дашборде:

1. Импортируйте репозиторий в Vercel.

2. В настройках проекта установите Root Directory = apps/web.

3. Vercel автоматически определит Next.js и всё настроит.

4. В разделе Environment Variables добавьте AUTH_SECRET (обязательно) и опционально KAITEN_API_URL.

Альтернативный способ — vercel.json в корне:

В корне репозитория уже есть vercel.json, который указывает Vercel собирать apps/web из корня монорепо. Просто импортируйте репозиторий без изменения Root Directory.

Подключение сотрудника в Claude Desktop

Settings → Connectors → Add custom connector → введите URL деплоя (например, https://kaiten-mcp.vercel.app). Claude Desktop запустит OAuth-флоу: откроется форма, где сотрудник вводит свой Kaiten API-токен. После этого все инструменты kaiten_* становятся доступны.

Архитектура монорепо

kaiten-mcp/
├── package.json                      # npm workspaces
├── packages/
│   ├── core/  (@kaiten-mcp/core)     # Общее ядро: клиент Kaiten, 36 инструментов,
│   │                                 # JWE-токены, проверка PKCE, типы
│   └── cli/   (kaiten-mcp)           # stdio MCP-сервер (npm-пакет, bin)
└── apps/
    └── web/   (@kaiten-mcp/web)      # Next.js удалённый сервер на Vercel,
                                      # OAuth 2.1 + PKCE + MCP-эндпоинт

Пакеты

• @kaiten-mcp/core — общая логика: клиент Kaiten API, все 36 инструментов, JWE seal/open (для OAuth-токенов), проверка PKCE S256, типы сущностей. Тесты: vitest.

• kaiten-mcp (packages/cli) — публикуемый npm-пакет, stdin/stdout MCP-сервер. Использует @kaiten-mcp/core. Тесты: smoke + elicitation.

• @kaiten-mcp/web (apps/web) — Next.js-приложение: OAuth 2.1 (PKCE + DCR), MCP-эндпоинт через mcp-handler. Тест: npm run test:flow.

Заметки по Kaiten API

• Базовый путь — /api/latest, аутентификация — Authorization: Bearer <token>.

• Тип колонки: 1 — очередь, 2 — в работе, 3 — готово.

• Состояние карточки condition: 1 — активная, 2 — архив.

• В search_cards редкие параметры Kaiten можно передавать через extra_params.

Лицензия

MIT