traker-mcp — MCP-сервер для Яндекс Трекера
Проще говоря: этот сервер учит вашего AI-ассистента работать с Яндекс Трекером. Вы говорите ассистенту «найди мои задачи», «создай задачу в очереди TREK», «закрой TASK-123 с резолюцией “Решён”» — а он делает это через API Трекера сам, без копирования ссылок руками.
Работает с любым MCP-клиентом: VS Code (Copilot), Cursor, Claude Desktop, Claude Code, opencode, Windsurf, Zed, JetBrains AI Assistant, Grok CLI.
📘 Подробное руководство для новичков (получение токена, пошаговая настройка каждого клиента, решение проблем) — в docs/SETUP.md.
Документация
Сайт документации (docs7) и LLM-индекс на Context7: context7.com/sdamarketing/tracker_mcp.
Отдельно: CHANGELOG и skills.sh-скилл.
Ресурсы и промпты (MCP)
Помимо инструментов сервер отдаёт:
- Resources (
resources/list,resources/read) — tracker:// URI для чтения контекста без вызова инструментов:tracker://issue/{KEY}— карточка задачи с описанием и последними 20 комментариями (markdown);tracker://queue/{KEY}— очередь + обязательные поля создания задач;tracker://board/{ID}— доска с колонками и статусами;tracker://catalog/statuses|priorities|types|resolutions|linktypes— справочники (делят TTL-кэш с инструментами);tracker://myself— ваш профиль.
- Prompts (
prompts/list,prompts/get) — готовые сценарии с аргументами:standup,weekly-report,triage,sprint-review,close-issue,create-issue. В клиентах с поддержкой промптов вызываются как slash-команды.
Что умеет
187 инструментов — полное покрытие API Трекера v3:
Безопасность для агентов
- Каждый инструмент несёт MCP-аннотации: чтения помечены
readOnlyHint, всеdelete_*—destructiveHint— клиенты показывают их как подтверждаемые/Безопасные операции. - Все
delete_*иbulk_*требуютconfirm: true(агент сначала показывает, что удалит). TRACKER_READ_ONLY=1— сервер отдаёт только 80 инструментов чтения, запись скрыта полностью. Для «просто посмотреть» интеграций.
Скилл для AI-агентов (skills.sh)
К серверу прилагается скилл yandex-tracker — процедурные знания для агента:
язык запросов Трекера, корректные значения полей (приоритеты, статусы, резолюции),
рецепты («найди мои задачи», «закрой с резолюцией», bulk-правки) и грабли API
(dueDate vs releaseDate, обязательная резолюция при закрытии, IAM-токены ≤12ч).
npx skills add sdamarketing/tracker_mcp
Устанавливает скилл во все обнаруженные агенты (Claude Code, Cursor, opencode,
Codex и ещё 75+). Мастер npm run setup тоже предлагает установить скилл
вместе с настройкой MCP-клиента. Репозиторий скилла: skills.sh/sdamarketing/tracker_mcp.
Установка в одну команду (macOS / Linux / WSL)
curl -fsSL https://raw.githubusercontent.com/sdamarketing/tracker_mcp/main/install.sh | bash
Скрипт сам: проверит систему → поставит Node.js через nvm, если его нет
(спросит согласия, sudo не нужен) → скачает сервер в ~/.traker-mcp → соберёт
и проверит его → запустит мастер настройки: ключи Трекера (ввод скрыт),
проверка ключей в API, выбор AI-клиента (VS Code, Cursor, Claude Desktop,
Claude Code, opencode, Windsurf, Zed, JetBrains, Grok CLI). Если команда grok
уже есть, мастер прописывает сервер в ~/.grok/config.toml сразу, до меню.
Повторный запуск той же командой = обновление сервера (конфиги клиентов не трогаются).
🔎 Хотите сначала прочитать скрипт? Уберите
| bashи посмотрите вывод:curl -fsSL https://raw.githubusercontent.com/sdamarketing/tracker_mcp/main/install.sh🪟 Windows: установите через WSL командой выше или вручную — см. ниже.
Установка из npm (без клонирования)
npm install -g tracker-mcp
tracker-mcp setup # интерактивный мастер: ключи Трекера + настройка AI-клиента
После этого сервер доступен командой tracker-mcp (в конфиг AI-клиента её и
прописывайте). Другие команды: tracker-mcp update, tracker-mcp links,
tracker-mcp --help.
Official MCP Registry
Сервер опубликован в официальном реестре MCP как
io.github.sdamarketing/tracker-mcp (npm + Docker-пакеты, env-переменные описаны
в server.json). Клиенты с поддержкой реестра найдут его по имени.
Docker (без установки чего-либо, кроме Docker)
Образ публикуется в GitHub Container Registry при каждом релизе (v*-тег):
# stdio (MCP-клиент запускает контейнер сам)
docker run -i --rm -e TRACKER_TOKEN -e TRACKER_ORG_ID ghcr.io/sdamarketing/tracker-mcp
# HTTP-режим
docker run --rm -p 3407:3407 -e TRACKER_TOKEN -e TRACKER_ORG_ID \
-e MCP_AUTH_TOKEN=вашключ ghcr.io/sdamarketing/tracker-mcp serve --host 0.0.0.0
В конфиге агента вместо command: node используется
command: docker, args: ["run","-i","--rm","-e","TRACKER_TOKEN","-e","TRACKER_ORG_ID","ghcr.io/sdamarketing/tracker-mcp"].
Ручная установка (Windows или без curl)
Шаг 1. Убедитесь, что есть Node.js 20+ (проверка: node -v).
Шаг 2. Соберите сервер:
git clone <адрес-этого-репозитория>
cd traker_mcp
npm install
npm run build
npm run smoke # проверка: должно быть "OK: ... 187 tools listed"
Шаг 3. Подготовьте две вещи из Трекера:
- токен — как получить: docs/SETUP.md, раздел 3
- ID организации — как найти: docs/SETUP.md, раздел 4
Шаг 4. Запустите мастер установки:
npm run setup
Мастер спросит ключи (токен — скрытым вводом), проверит их в API Трекера, покажет интерактивное меню клиентов (↑↓ + Enter) и настроит выбранные (можно несколько подряд) — через их CLI или дописав конфиг с бэкапом, — а в конце выведет отчёт.
Альтернатива: npm run links — откроет страницу в браузере с кнопками
установки в один клик (VS Code, Cursor, Claude Desktop) и конфигами всех
клиентов для ручного копирования.
Подключение к вашему агенту
Пошаговые инструкции с точными путями для macOS/Windows/Linux: docs/SETUP.md.
Проверка
После установки перезапустите агента и спросите:
«Вызови инструмент get_current_user» — вернётся ваш профиль из Трекера. «Найди мои задачи в Трекере» — сработает find_issues.
Частые проблемы
Больше решений — docs/SETUP.md, раздел 8.
Настройка сервера
HTTP-режим (serve)
По умолчанию сервер работает по stdio (для локальных агентов). Для сетевого доступа (команда, удалённый клиент, проксирование):
tracker-mcp serve --port 3407 --host 127.0.0.1 # значения по умолчанию
MCP_AUTH_TOKEN=s3cret tracker-mcp serve # ключ к эндпоинту (Bearer)
curl localhost:3407/health # {"ok":true,"tools":187}
- Эндпоинт MCP:
POST/GET/DELETE /mcp(Streamable HTTP, stateless) - Без
MCP_AUTH_TOKENпривязка к не-loopback-адресу отклоняется — токен Трекера живёт в env, голый порт в сети недопустим - Конфиг клиента для HTTP:
"url": "http://127.0.0.1:3407/mcp"+"headers": {"Authorization": "Bearer s3cret"}
Безопасность
- Токен даёт агенту те же права, что у вас в Трекере. Выдавайте минимальные
права (для чтения хватит
tracker:read). - Храните токен в
.env(уже в.gitignore) или в конфиге клиента, не в коде. install-links.htmlсодержит токен — скрипт добавляет его в.gitignoreсам.
Разработка
npm run typecheck # проверка типов
npm run build # сборка в dist/
npm run smoke # запуск и список инструментов без обращения к API
npm run setup # интерактивный мастер установки для AI-клиентов
npm run links # страница с кнопками установки (deeplinks)
Архитектура и полный список инструментов — в docs/SETUP.md и в коде src/tools/.
Лицензия и поддержка
Проблемы и идеи — в issues репозитория. API Трекера меняется — следите за официальной документацией.
