yandex-tracker-mcp

MCP-сервер для Yandex Tracker API. Позволяет AI-ассистентам (Claude Code и совместимые клиенты) искать, читать, создавать и редактировать задачи, а также работать с комментариями, вложениями и связями в Yandex Tracker.

Подключение

Порядок одинаковый для любого MCP-клиента:

1. Получить OAuth-токен (один раз, локально).
2. Прописать сервер в конфиге клиента (JSON — Claude Code / Claude Desktop / Cursor, TOML — Codex).
3. Перезапустить клиент.

Шаг 1. Получите OAuth-токен и ID организации

Откройте https://tracker.yandex.ru/ и определите тип организации:

• Яндекс 360 для бизнеса — нужен org-id (узнать: https://admin.yandex.ru/ → «Об организации»)
• Yandex Cloud Organization — нужен cloud-org-id (узнать: https://console.yandex.cloud/ → «Все организации»)

Запустите один раз локально — откроется браузер с авторизацией Яндекса:

npx -y yandex-tracker-mcp --org-id YOUR_ORG_ID --auth
# или
npx -y yandex-tracker-mcp --cloud-org-id YOUR_CLOUD_ORG_ID --auth

CLI использует встроенное OAuth-приложение yandex-tracker-mcp и проходит авторизацию по PKCE (RFC 7636) — без client_secret. Если вы хотите использовать собственное OAuth-приложение (корпоративная политика, отдельное логирование и т. п.), зарегистрируйте его на oauth.yandex.ru с Redirect URI http://localhost:27311/callback и правами tracker:read, tracker:write, после чего передайте --client-id YOUR_APP_ID.

Токен автоматически сохраняется в ~/.config/yandex-tracker-mcp/token.json (права 0600) и оттуда же читается при последующих запусках — access_token никуда копировать не нужно. При истечении срока сервер сам обновит его через refresh_token.

Шаг 2. Пропишите сервер в конфиге клиента

Все клиенты, кроме Codex, используют одинаковый JSON-формат mcpServers. Codex использует TOML. OAuth-токен в конфиге указывать не нужно — он читается из ~/.config/yandex-tracker-mcp/token.json автоматически. TRACKER_USERNAME — имя-фамилия для фильтра search_issues по умолчанию (опционально).

Базовый пример для Яндекс 360 для бизнеса:

{
  "mcpServers": {
    "yandex-tracker": {
      "command": "npx",
      "args": ["-y", "yandex-tracker-mcp"],
      "env": {
        "TRACKER_ORG_ID": "1234567",
        "TRACKER_USERNAME": "Иван Иванов"
      }
    }
  }
}

Для Yandex Cloud Organization замените TRACKER_ORG_ID на TRACKER_CLOUD_ORG_ID (значение — алфавитно-цифровой ID).

Claude Code

Путь конфига — .mcp.json в корне проекта (project-scoped, можно коммитить: ID организации не секрет). Положите в него JSON-пример выше.

Альтернатива через CLI (user-scoped, доступно во всех проектах). Stdio:

claude mcp add yandex-tracker --transport stdio \
  --env TRACKER_ORG_ID=1234567 \
  --env TRACKER_USERNAME="Иван Иванов" \
  -- npx -y yandex-tracker-mcp

На Windows (без WSL) npx требуется оборачивать в cmd /c: -- cmd /c npx -y yandex-tracker-mcp.

Claude Desktop

Settings → Developer → Edit Config, либо прямо откройте файл:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Положите туда тот же JSON-пример. Если файл пустой — используйте пример целиком. Если уже есть другие MCP-серверы — добавьте ключ "yandex-tracker" внутрь существующего mcpServers.

Cursor

Путь конфига:

• Проект: .cursor/mcp.json в корне проекта
• Глобально: ~/.cursor/mcp.json

Формат — тот же JSON mcpServers. После сохранения Cursor подхватит сервер (или перезагрузите окно через Cmd/Ctrl+Shift+P → «Reload Window»).

Codex CLI / Codex IDE extension

Codex использует TOML. Путь конфига:

• Глобально: ~/.codex/config.toml
• Проект (только для trusted-проектов): .codex/config.toml

[mcp_servers.yandex-tracker]
command = "npx"
args = ["-y", "yandex-tracker-mcp"]

[mcp_servers.yandex-tracker.env]
TRACKER_ORG_ID = "1234567"
TRACKER_USERNAME = "Иван Иванов"

Для Yandex Cloud Organization замените TRACKER_ORG_ID на TRACKER_CLOUD_ORG_ID.

codex mcp add yandex-tracker \
  --env TRACKER_ORG_ID=1234567 \
  --env TRACKER_USERNAME="Иван Иванов" \
  -- npx -y yandex-tracker-mcp

Один и тот же config.toml используется и CLI, и IDE-расширением Codex.

Шаг 3. Перезапустите клиент и проверьте

• Claude Code: claude в корне проекта → подтвердите project-scoped MCP при первом запуске → /mcp покажет статус connected.
• Claude Desktop: полностью закройте приложение (Cmd+Q / из системного трея) и откройте заново. Индикатор MCP появится в правом нижнем углу поля ввода.
• Cursor: перезагрузите окно (Cmd/Ctrl+Shift+P → «Reload Window») либо Cursor целиком. В Settings → MCP сервер должен быть зелёным.
• Codex CLI: codex mcp list — сервер должен быть connected.

Фильтры по умолчанию

search_issues автоматически добавляет к TQL-запросу:

• AND Assignee: "<TRACKER_USERNAME>" — если задано и в query нет Assignee:.
• AND Queue: <TRACKER_DEFAULT_QUEUE> — если задано и в query нет Queue:.
• AND Project: <TRACKER_DEFAULT_PROJECT> — если задано и в query нет Project:.

Любое явное упоминание соответствующего поля в самом query отключает автоподстановку. Параметр assignee при вызове search_issues тоже переопределяет дефолт.

create_issue подставляет TRACKER_DEFAULT_QUEUE и TRACKER_DEFAULT_PROJECT, если соответствующие параметры не переданы. update_issue подставляет только TRACKER_DEFAULT_PROJECT (при явном отсутствии поля). get_queue_local_fields принимает queueKey опционально и фолбэчится на TRACKER_DEFAULT_QUEUE.

ФИО → login

В полях assignee и followers (create_issue, update_issue) можно передавать ФИО на русском — сервер сам резолвит их в login через справочник /v3/users. Для явного поиска пользователя используйте find_user — он принимает подстроку имени, login или email и возвращает [{login, display, email}].

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

| Переменная | Назначение | |---|---| | TRACKER_ORG_ID | ID организации Яндекс 360 для бизнеса (заголовок X-Org-ID) | | TRACKER_CLOUD_ORG_ID | ID Yandex Cloud Organization (заголовок X-Cloud-Org-ID) | | TRACKER_USERNAME | Имя и фамилия для автоматического фильтра Assignee: в search_issues. Опционально | | TRACKER_DEFAULT_QUEUE | Очередь по умолчанию. Используется в search_issues (TQL Queue:), create_issue (поле queue), get_queue_local_fields (поле queueKey). Опционально | | TRACKER_DEFAULT_PROJECT | Проект по умолчанию. Числовой shortId. Используется в search_issues (TQL Project:), create_issue / update_issue (поле project в формате v3 {primary:{shortId}}). Опционально. Нечисловое значение применяется только в TQL-фильтре | | TRACKER_OAUTH_TOKEN | Опционально. Переопределяет токен из ~/.config/yandex-tracker-mcp/token.json |

Указывайте ровно один из TRACKER_ORG_ID / TRACKER_CLOUD_ORG_ID — в зависимости от типа вашей организации.

Доступные инструменты

| Инструмент | Описание | |------------|----------| | get_issue | Получить задачу по ключу (например QUEUE-123) | | search_issues | Поиск задач на языке запросов Трекера (например Queue: MYQUEUE AND Status: Open) | | create_issue | Создать новую задачу (очередь, название, описание, тип, приоритет, исполнитель и др.) | | update_issue | Изменить существующую задачу (название, описание, приоритет, исполнитель и др.) | | get_transitions | Получить доступные переходы статуса для задачи | | transition_issue | Перевести задачу в другой статус (выполнить переход) | | get_comments | Получить все комментарии к задаче | | create_comment | Добавить комментарий к задаче (с поддержкой summonees — упоминаний и attachmentIds) | | get_attachments | Получить метаданные вложений (имя, размер, MIME-тип, id) | | download_attachment | Скачать вложение в base64. Изображения возвращаются как image-блоки | | get_issue_links | Получить все связи задачи | | create_issue_link | Создать связь между задачами (relates, depends on, is dependent by, duplicates, is subtask for и др.) | | get_checklist | Получить чеклист задачи | | get_statuses | Получить список всех статусов | | get_issue_types | Получить список типов задач (задача, баг, история и т.д.) | | get_resolutions | Получить список резолюций | | get_priorities | Получить список приоритетов | | get_queues | Получить список очередей | | get_queue_local_fields | Получить локальные (кастомные) поля очереди | | get_global_fields | Получить глобальные (системные) поля | | get_entity | Получить параметры сущности (проект, портфель) по типу и ID | | find_user | Найти пользователей по подстроке ФИО, login или email. Возвращает [{login, display, email}] |

Лицензия

MIT