odnashestaia/mcp_server

Kaiten MCP Server

MCP-сервер для работы с Kaiten (Spaces, Boards, Cards): CRUD-инструменты, запуск по STDIO, поддержка MCP Inspector и встроенный мини-клиент.

Требования

Python 3.11 или 3.12 uv (менеджер пакетов/раннер)

• Linux/macOS: curl -Ls https://astral.sh/uv/install.sh | sh
• Windows PowerShell: irm https://astral.sh/uv/install.ps1 | iex

Проект ожидает, что запуск выполняется с PYTHONPATH, содержащим каталог src.

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

Создайте файл .env в корне проекта или экспортируйте переменные вручную. .env.example

KAITEN_BASE_URL=https://nikolay1979laptop.kaiten.ru/api/v1
KAITEN_API_TOKEN=00000000000000000000000000000000
RPS_LIMIT=5
REQUEST_TIMEOUT=20
LOG_LEVEL=INFO
PYTHONPATH=src

Значения приведены для примера. Укажите реальный токен и корректный URL вашего Kaiten.

Установка зависимостей

uv sync

При отсутствии lock-файла зависимости могут устанавливаться на лету через uv run.

Запуск локально

npx @modelcontextprotocol/inspector

После запуска сервер слушает STDIO в формате MCP.

Вызов инструментов

MCP Inspector (STDIO):

Настройки подключения:

• Transport Type: STDIO
• Command: uv
• Arguments: run -m server.server serve

Далее нажмите Connect. В tools для каждого инструмента в поле Arguments (запрос) передавайте JSON с верхним ключом params.

Примеры JSON для Inspector.

Spaces:

{"params": {}}

{"params": {"space_id": "1001"}}

{"params": {"title": "Новое пространство", "external_id": 9001}}

{"params": {"space_id": 1001, "title": "Обновлённое", "allowed_card_type_ids": [1,2], "external_id": 9002}}

{"params": {"space_id": "1001"}}

Boards:

{"params": {"space_id": "1001", "cursor": null, "limit": 50}}

{"params": {"space_id": "1001", "board_id": "2001"}}

{"params": {
  "space_id": "1001",
  "title": "Новая доска",
  "description": "Описание",
  "lanes": [ {"title": "Lane A"} ],
  "columns": [ {"title": "To Do", "type": 1}, {"title": "Doing", "type": 2}, {"title": "Done", "type": 3} ]
}}

{"params": {"space_id": "1001", "board_id": "2001", "title": "Доработанное имя", "description": "Апдейт"}}

{"params": {"space_id": "1001", "board_id": "2001"}}

Cards:

{"params": {"board_id": "2001", "cursor": null, "limit": 50}}

{"params": {"card_id": "3001"}}

{"params": {
  "title": "Моя новая задача",
  "board_id": 2001,
  "description": "Описание новой задачи",
  "lane_id": 1782805,
  "column_id": 5051439,
  "asap": false,
  "due_date_time_present": false,
  "properties": {}
}}

{"params": {"card_id": 3001, "title": "Переименовано", "description": "Новый текст"}}

{"params": {"card_id": 3001}}

Замечание: ошибка Invalid request parameters почти всегда связана с отсутствием обёртки {"params": ...}.

Встроенный мини-клиент

Серверный модуль содержит встроенный мини-клиент для вызова инструментов по STDIO.

Показать список инструментов:

uv run -m server.server client-list --cmd "uv run -m server.server serve"

Вызвать инструмент (Linux/macOS):

uv run -m server.server client-call --cmd "uv run -m server.server serve" spaces_list "{}"

uv run -m server.server client-call --cmd "uv run -m server.server serve" spaces_get '{"space_id":"1001"}'

uv run -m server.server client-call --cmd "uv run -m server.server serve" cards_create '{"title":"Моя новая задача","board_id":2001,"description":"Описание"}'

Вызвать инструмент (Windows PowerShell):

uv run -m server.server client-call --cmd "uv run -m server.server serve" spaces_list "{}"

uv run -m server.server client-call --cmd "uv run -m server.server serve" spaces_get "{\"space_id\":\"1001\"}"

Мини-клиент автоматически оборачивает параметры в {"params": ...}, если верхний ключ не указан. Флаг --no-wrap отключает автообёртку.

Примеры успешных сценариев CRUD

Ниже цепочки действий, которые можно выполнить через Inspector или мини-клиент.

Spaces

1. Create: spaces_create — возвращает id нового пространства.
2. Get: spaces_get с полученным id.
3. Update: spaces_update, изменив title или allowed_card_type_ids.
4. List: spaces_list, при необходимости с пагинацией.
5. Delete: spaces_delete и проверка отсутствия пространства в списке.
6. Ожидаемый результат — ответы со статусом ok и корректные данные, после удаления объект отсутствует в выдаче.

Boards

1. Create: boards_create внутри нужного space_id, с columns и lanes.
2. Get: boards_get по board_id.
3. List: boards_list по space_id.
4. Update: boards_update (title и/или description).
5. Delete: boards_delete и проверка отсутствия в boards_list.

Cards

1. Create: cards_create минимум с title и board_id; опционально lane_id, column_id, description.
2. Get: cards_get по card_id.
3. List: cards_list по board_id или space_id.
4. Update: cards_update (title, description).
5. Delete: cards_delete и проверка отсутствия карточки в списке.