@mmtr-tech/yandex-tracker-mcp

MCP-сервер для API Яндекс Трекера (OAuth + организация Яндекс 360).

English version

Установка / запуск в Cursor

{
  "mcpServers": {
    "yandex-tracker": {
      "command": "npx",
      "args": ["-y", "@mmtr-tech/yandex-tracker-mcp"],
      "env": {
        "API_TOKEN": "your-oauth-token",
        "X_ORG_ID": "your-org-id"
      }
    }
  }
}

Опционально: "API_BASE_URL": "https://api.tracker.yandex.net/v3" (это значение по умолчанию).

После изменения конфига — Restart Cursor (toggle MCP часто недостаточен).

Env

| Переменная | Обязательно | Описание | |------------|-------------|----------| | API_TOKEN | да | OAuth-токен (Authorization: OAuth …) | | X_ORG_ID | да | Id организации Яндекс 360 (X-Org-ID) | | API_BASE_URL | нет | По умолчанию https://api.tracker.yandex.net/v3 |

Как получить OAuth-токен и X_ORG_ID

Нужны OAuth-токен пользователя Трекера и id организации Яндекс 360.

1. Зарегистрировать приложение в Яндекс OAuth

Инструкция по типам приложений: Регистрация приложения.

Для этого MCP выбирайте тип «Для доступа к API или отладки» (не «для авторизации пользователей»). Тип после создания не меняется.

1. Откройте oauth.yandex.ru → Создать.
2. Выберите Для доступа к API или отладки.
3. Укажите название и почту.
4. В поле доступов добавьте:
   • tracker:read — только чтение;
   • tracker:write — создание/правка/комменты/переходы (нужен для write-tools).
5. Создайте приложение и скопируйте ClientID.

Подробнее по Трекеру: Доступ к API → OAuth.

2. Выпустить токен

https://oauth.yandex.ru/authorize?response_type=token&client_id=<ClientID>

Откройте ссылку под аккаунтом, от имени которого будете ходить в Трекер. Появившаяся строка — это API_TOKEN.

Токен действует с правами этого пользователя. Отозвать доступ можно в настройках Яндекс ID.

3. Узнать X_ORG_ID

В Трекере: Администрирование → Организации → скопируйте идентификатор (X-Org-ID).

4. Проверить доступ

curl -X GET 'https://api.tracker.yandex.net/v3/myself' \
  -H "Authorization: OAuth $API_TOKEN" \
  -H "X-Org-ID: $X_ORG_ID"

Ожидается 200 и JSON с login / display. 401 — неверный токен, scopes или org id.

Tools

Чтение

| Tool | API | |------|-----| | get_myself | GET /myself | | get_user | GET /users/{id} | | list_users | GET /users | | list_queues | GET /queues/ | | get_queue | GET /queues/{id} | | list_queue_versions | GET /queues/{id}/versions | | list_queue_components | GET /queues/{id}?expand=components | | get_issue | GET /issues/{id} | | search_issues | POST /issues/_search | | count_issues | POST /issues/_count | | get_issue_comments | GET /issues/{id}/comments | | get_issue_links | GET /issues/{id}/links | | get_issue_transitions | GET /issues/{id}/transitions | | get_issue_changelog | GET /issues/{id}/changelog | | get_issue_attachments | метаданные вложений | | get_issue_worklog | GET /issues/{id}/worklog | | search_worklog | POST /worklog/_search | | get_worklog_summary | агрегация поверх search_worklog | | get_my_worklog_for_month | мои часы за календарный месяц (login сам) | | get_issue_checklist | GET /issues/{id}/checklistItems | | list_boards | GET /boards/ | | list_board_sprints | GET /boards/{id}/sprints |

search_issues / count_issues: укажите ровно один режим (query или filter; у search ещё keys / queue).

Примеры query: Queue: TEST, Queue: TEST Assignee: me() Sort by: Updated DESC, Key: TEST-1, "Time Spent": >"2d".

Учёт времени (worklog)

В Трекере две даты: start (день работы) и createdAt (когда запись сохранили). Обычно отчёт нужен по start.

| Tool | Когда | Аргументы | |------|-------|-----------| | get_my_worklog_for_month | По умолчанию для «мои часы за месяц / сентябрь» | Лучше не передавать month → текущий месяц сервера. Или month: "YYYY-MM". Опционально groupBy: day|issue, by: start (по умолчанию) | createdAt. В ответе есть serverMonth / serverNow. | | get_worklog_summary | Другой пользователь или свой диапазон | Обязательно: createdBy, startFrom, startTo (YYYY-MM-DD). Опционально groupBy, queuePrefix только если пользователь назвал очередь. | | search_worklog | Сырые строки | Те же фильтры, что у summary; список записей. | | get_issue_worklog | Только одна известная задача | issueId, опц. startFrom/startTo. Не для месячного отчёта по пользователю. |

Не кладите период отчёта в createdAtFrom/createdAtTo, если не фильтруете именно по дате сохранения (by: "createdAt" / restrictCreatedAt). Нельзя search_issues(queue) + get_issue_worklog по всей очереди.

Запись (побочные эффекты)

| Tool | API | |------|-----| | create_issue | POST /issues/ (+ опц. fields) | | update_issue | PATCH /issues/{id} (+ fields / операторы) | | add_issue_comment | POST /issues/{id}/comments (+ опц. attachmentIds) | | execute_transition | переход статуса | | create_issue_link / delete_issue_link | связи | | add_issue_followers / remove_issue_followers | наблюдатели | | add_issue_worklog | списание времени | | update_issue_worklog / delete_issue_worklog | правка / удаление списания | | update_checklist_item | чеклист | | upload_issue_attachment | загрузка с локального filePath; embed=true — комментарий с файлом |

Статус меняется только через execute_transition (сначала get_issue_transitions). Нужен OAuth scope tracker:write.

License

MIT