Yandex Tracker

traker-mcp — 用于 Яндекс Трекер 的 MCP 服务

简单来说：这个服务能教你的 AI 助手使用 Яндекс Трекер。 你可以告诉助手“查找我的任务”“在 TREK 队列中创建任务”“将 TASK-123 以‘已解决’为解决方案关闭”——它会自行通过 Tracker API 完成，无需手动复制链接。

适用于任何 MCP 客户端：VS Code (Copilot)、Cursor、Claude Desktop、 Claude Code、opencode、Windsurf、Zed、JetBrains AI Assistant、Grok CLI。

📘 面向新手的详细指南（获取令牌、逐步配置各个客户端、排查问题）请见 docs/SETUP.md。

文档

文档网站（docs7）和 Context7 上的 LLM 索引： context7.com/sdamarketing/tracker_mcp。

部分	内容
开始使用	概览、快速入门、安装、客户端
运行与维护	工具、资源和提示词、HTTP 服务、安全
功能指南	任务 · 评论/检查清单/worklog/文件 · 队列 · 看板和冲刺 · 项目/目标/项目组合 · 自动化 · 管理 · 架构
参考资料	SETUP · API 覆盖范围 · 故障排查 · FAQ

另请参阅：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。在支持提示词的客户端中，可通过斜杠命令调用。

功能

187 个工具——全面覆盖Tracker v3 API：

类别	可执行的操作
任务	搜索（筛选器、查询语言、query 2.0、scroll >10k、提示）、创建、读取、编辑、转移、更改状态、关联、历史记录
评论	添加、读取（列表和单条）、编辑、删除、反应
清单	任务 + 项目／组合：添加、标记、移动、删除
时间跟踪	按任务记录时间，以及按作者／日期搜索
附件	列表、元数据、下载（图片／文本／数据库）、缩略图、上传、临时文件
批量操作	编辑、转移和关闭任务；批量更新项目／目标
报告和筛选器	用于小组件的已保存报告、已保存筛选器的 CRUD
队列	CRUD（包括删除／恢复）、访问权限、版本、组件、本地字段、宏、标签
自动化	触发器和自动操作（CRUD + 日志）、工作流（状态和转换）
看板	CRUD、分页、列 CRUD、冲刺（创建／启动／归档）
仪表盘	创建仪表盘和小组件（“周期时间”）
项目、目标、组合	CRUD、评论、清单、附件、关联、事件、权限、关键结果和指标（通过 fields）
参考数据	读取和写入：类型、状态、优先级、解决方案；全局字段和类别
外部应用	将任务与外部系统（Jira 等）关联
缺勤	休假／病假／出差（admin）
迁移	“追溯”导入任务／评论／关联／工时／附件（admin）

面向 Agent 的安全保障

• 每个工具都带有 MCP 注释：读取操作标记为 readOnlyHint，所有 delete_* 操作标记为 destructiveHint——客户端会将它们显示为需确认／安全操作。
• 所有 delete_* 和 bulk_* 操作都需要 confirm: true（Agent 会先显示将要删除的内容）。
• TRACKER_READ_ONLY=1——服务仅提供 80 个读取工具，完全隐藏写入操作。适用于“只查看”的集成。

AI Agent 技能（skills.sh）

此服务附带 yandex-tracker 技能——为 Agent 提供程序性知识： Tracker 查询语言、字段的正确取值（优先级、状态、解决方案）、 操作指南（“查找我的任务”“使用解决方案关闭”“批量修改”）以及 API 常见问题 （dueDate 与 releaseDate 的区别、关闭任务时必须指定解决方案、IAM 令牌有效期 ≤12 小时）。

npx skills add sdamarketing/tracker_mcp

为所有检测到的 Agent 安装技能（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 → 构建并检查服务 → 启动配置向导：输入 Tracker 密钥（输入内容会隐藏），在 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。

官方 MCP Registry

该服务已发布到官方 MCP Registry，名称为 io.github.sdamarketing/tracker-mcp（npm + Docker 软件包，环境变量见 server.json）。支持 Registry 的客户端可以按名称找到它。

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

在 Agent 配置中，将 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。 准备好从 Tracker 获取的两项信息：

• 令牌 — 获取方法：docs/SETUP.md，第 3 节
• 组织 ID — 查找方法：docs/SETUP.md，第 4 节

步骤 4。 运行安装向导：

npm run setup

向导会询问密钥（令牌以隐藏输入方式输入），并在 Tracker API 中验证密钥，然后显示交互式客户端菜单（↑↓ + Enter）并配置所选客户端（可连续选择多个）—— 通过客户端的 CLI，或在配置文件末尾追加内容并创建备份——最后输出报告。

另一种方式：npm run links — 将在浏览器中打开一个页面，提供一键安装按钮 （VS Code、Cursor、Claude Desktop）以及所有客户端的配置，供手动复制。

连接到你的 Agent

你的 Agent	快速方式	配置文件
VS Code（Copilot）	npm run setup（CLI code）	.vscode/mcp.json
Cursor	npm run setup	~/.cursor/mcp.json
Claude Desktop	npm run setup	claude_desktop_config.json
Claude Code（终端）	npm run setup（CLI claude）	~/.claude.json
opencode	npm run setup	~/.config/opencode/opencode.json
Windsurf	npm run setup	~/.codeium/windsurf/mcp_config.json
Zed	npm run setup	settings.json（context_servers）
JetBrains IDE	npm run setup	项目根目录中的 .mcp.json
Grok CLI	npm run setup（如果存在 grok，则自动配置）	~/.grok/config.toml

macOS/Windows/Linux 的分步说明及准确路径： docs/SETUP.md。

验证

安装后重启 Agent，并提问：

“调用工具 get_current_user” — 将返回你的 Tracker 个人资料。 “查找我在 Tracker 中的任务” — 将调用 find_issues。

常见问题

症状	原因及解决方法
Missing required environment variable TRACKER_TOKEN	未传入令牌 — 重新生成链接（npm run links），或检查配置中的 env
Yandex Tracker API error 401	令牌无效或已过期（IAM 有效期 ≤12 小时）
Yandex Tracker API error 403: Organization is not available	TRACKER_ORG_ID 无效，或组织尚未接入 Tracker
服务无法在 Claude Desktop（macOS）中启动	请使用 node 的绝对路径 — 生成的配置中已使用绝对路径
Agent 没有工具	服务已禁用 — 请在客户端的 MCP 服务列表中启用并重启

更多解决方案 — docs/SETUP.md，第 8 节。

服务配置

变量	必填	描述
TRACKER_TOKEN	是	OAuth 令牌（y0_...，Yandex 360）或 IAM 令牌（t1....，Yandex Cloud）
TRACKER_ORG_ID	是	组织标识符
TRACKER_AUTH	否	oauth（默认）或 iam — 用于确定 X-Org-ID / X-Cloud-Org-ID 标头
TRACKER_API_URL	否	默认为 https://api.tracker.yandex.net/v3
TRACKER_LANG	否	ru 或 en — 本地化字段的语言
TRACKER_READ_ONLY	否	1 — Agent 仅可使用只读工具（80 个）
TRACKER_CACHE_TTL_MS	否	参考数据缓存的 TTL（默认 10 分钟）

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 Трекера меняется — следите за официальной документацией.