Yandex Tracker Mcp

开发 Python

🚀 Yandex Tracker MCP Server

Yandex Tracker MCP Server 是一个全面的模型上下文协议（MCP）服务器，它使 AI 助手能够与 Yandex Tracker API 进行交互。该服务器提供对 Yandex Tracker 问题、队列、评论、工作日志和搜索功能的安全、经过身份验证的访问，并可选配 Redis 缓存以提高性能。

点击此处查看俄文文档

🚀 快速开始

该项目提供了便捷的使用方式，你可以通过多种途径进行安装和配置，以实现与 Yandex Tracker API 的交互。下面将详细介绍不同场景下的安装和配置方法。

✨ 主要特性

完整的队列管理：列出并访问所有可用的 Yandex Tracker 队列，支持分页和标签检索。
用户管理：检索用户账户信息，包括登录详情、电子邮件地址、许可证状态和组织数据。
问题操作：检索详细的问题信息、评论、相关链接、工作日志和附件。
字段管理：访问全局字段、特定队列的本地字段、状态和问题类型。
高级查询语言：全面支持 Yandex Tracker 查询语言，具备复杂的过滤、排序和日期功能。
性能缓存：可选的 Redis 缓存层，以提高响应时间。
安全控制：可配置的队列访问限制和安全的令牌处理。
多种传输选项：支持标准输入输出（stdio）、服务器发送事件（SSE，已弃用）和 HTTP 传输，便于灵活集成。
OAuth 2.0 身份验证：基于动态令牌的身份验证，支持自动刷新，可替代静态 API 令牌。
组织支持：兼容标准和云组织 ID。

组织 ID 配置

根据你的 Yandex 组织类型，选择以下其中一种配置：

Yandex 云组织：对于由 Yandex 云管理的组织，后续使用 TRACKER_CLOUD_ORG_ID 环境变量。
Yandex 360 组织：对于 Yandex 360 组织，后续使用 TRACKER_ORG_ID 环境变量。

你可以在 Yandex Tracker URL 或组织设置中找到你的组织 ID。

📦 安装指南

在 Claude Desktop 中安装扩展

Yandex Tracker MCP Server 可以作为扩展一键安装到 Claude Desktop 中。

前提条件

系统中必须安装 Python 3.12。对于 macOS 用户，可以使用以下命令进行安装：

brew install python@3.12

安装步骤

从 GitHub 发布页面为你的操作系统和平台下载 *.dxt 文件。
双击下载的文件，将其安装到 Claude Desktop 中。
当提示时，提供你的 Yandex Tracker OAuth 令牌。
确保扩展已启用，现在你可以使用此 MCP Server 了。

手动安装

前提条件

全局安装 uv。
拥有具有适当权限的有效 Yandex Tracker API 令牌。

以下部分展示了如何为不同的 AI 客户端配置 MCP 服务器。你可以使用 uvx yandex-tracker-mcp@latest 或 Docker 镜像 ghcr.io/aikts/yandex-tracker-mcp:latest。两者都需要以下环境变量：

身份验证（以下任选其一）：
- TRACKER_TOKEN - 你的 Yandex Tracker OAuth 令牌。
- TRACKER_IAM_TOKEN - 你的 IAM 令牌。
- TRACKER_SA_KEY_ID、TRACKER_SA_SERVICE_ACCOUNT_ID、TRACKER_SA_PRIVATE_KEY - 服务账户凭证。
TRACKER_CLOUD_ORG_ID 或 TRACKER_ORG_ID - 你的 Yandex 云（或 Yandex 360）组织 ID。

Claude Desktop

配置文件路径：

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

使用 uvx：

{
"mcpServers": {
"yandex-tracker": {
"command": "uvx",
"args": ["yandex-tracker-mcp@latest"],
"env": {
"TRACKER_TOKEN": "your_tracker_token_here",
"TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here",
"TRACKER_ORG_ID": "your_org_id_here"
}
}
}
}

使用 Docker：

{
"mcpServers": {
"yandex-tracker": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "TRACKER_TOKEN",
"-e", "TRACKER_CLOUD_ORG_ID",
"-e", "TRACKER_ORG_ID",
"ghcr.io/aikts/yandex-tracker-mcp:latest"
],
"env": {
"TRACKER_TOKEN": "your_tracker_token_here",
"TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here",
"TRACKER_ORG_ID": "your_org_id_here"
}
}
}
}

Claude Code

使用 uvx：

claude mcp add yandex-tracker uvx yandex-tracker-mcp@latest \
-e TRACKER_TOKEN=your_tracker_token_here \
-e TRACKER_CLOUD_ORG_ID=your_cloud_org_id_here \
-e TRACKER_ORG_ID=your_org_id_here \
-e TRANSPORT=stdio

使用 Docker：

claude mcp add yandex-tracker docker "run --rm -i -e TRACKER_TOKEN=your_tracker_token_here -e TRACKER_CLOUD_ORG_ID=your_cloud_org_id_here -e TRACKER_ORG_ID=your_org_id_here -e TRANSPORT=stdio ghcr.io/aikts/yandex-tracker-mcp:latest"

Cursor

配置文件路径：

项目特定：项目目录下的 .cursor/mcp.json
全局：~/.cursor/mcp.json

使用 uvx：

{
"mcpServers": {
"yandex-tracker": {
"command": "uvx",
"args": ["yandex-tracker-mcp@latest"],
"env": {
"TRACKER_TOKEN": "your_tracker_token_here",
"TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here",
"TRACKER_ORG_ID": "your_org_id_here"
}
}
}
}

使用 Docker：

{
"mcpServers": {
"yandex-tracker": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "TRACKER_TOKEN",
"-e", "TRACKER_CLOUD_ORG_ID",
"-e", "TRACKER_ORG_ID",
"ghcr.io/aikts/yandex-tracker-mcp:latest"
],
"env": {
"TRACKER_TOKEN": "your_tracker_token_here",
"TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here",
"TRACKER_ORG_ID": "your_org_id_here"
}
}
}
}

Windsurf

配置文件路径：

~/.codeium/windsurf/mcp_config.json

访问方式：Windsurf 设置 → 级联标签 → 模型上下文协议（MCP）服务器 → "查看原始配置"

使用 uvx：

{
"mcpServers": {
"yandex-tracker": {
"command": "uvx",
"args": ["yandex-tracker-mcp@latest"],
"env": {
"TRACKER_TOKEN": "your_tracker_token_here",
"TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here",
"TRACKER_ORG_ID": "your_org_id_here"
}
}
}
}

使用 Docker：

{
"mcpServers": {
"yandex-tracker": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "TRACKER_TOKEN",
"-e", "TRACKER_CLOUD_ORG_ID",
"-e", "TRACKER_ORG_ID",
"ghcr.io/aikts/yandex-tracker-mcp:latest"
],
"env": {
"TRACKER_TOKEN": "your_tracker_token_here",
"TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here",
"TRACKER_ORG_ID": "your_org_id_here"
}
}
}
}

Zed

配置文件路径：

~/.config/zed/settings.json

访问方式：Cmd+,（macOS）或 Ctrl+,（Linux/Windows）或命令面板："zed: 打开设置"

注意：需要 Zed 预览版才能支持 MCP。

使用 uvx：

{
"context_servers": {
"yandex-tracker": {
"source": "custom",
"command": {
"path": "uvx",
"args": ["yandex-tracker-mcp@latest"],
"env": {
"TRACKER_TOKEN": "your_tracker_token_here",
"TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here",
"TRACKER_ORG_ID": "your_org_id_here"
}
}
}
}
}

使用 Docker：

{
"context_servers": {
"yandex-tracker": {
"source": "custom",
"command": {
"path": "docker",
"args": [
"run", "--rm", "-i",
"-e", "TRACKER_TOKEN",
"-e", "TRACKER_CLOUD_ORG_ID",
"-e", "TRACKER_ORG_ID",
"ghcr.io/aikts/yandex-tracker-mcp:latest"
],
"env": {
"TRACKER_TOKEN": "your_tracker_token_here",
"TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here",
"TRACKER_ORG_ID": "your_org_id_here"
}
}
}
}
}

GitHub Copilot (VS Code)

配置文件路径：

工作区：项目目录下的 .vscode/mcp.json
全局：VS Code 的 settings.json

选项 1：工作区配置（推荐用于安全）

创建 .vscode/mcp.json：

使用 uvx：

{
"inputs": [
{
"type": "promptString",
"id": "tracker-token",
"description": "Yandex Tracker Token",
"password": true
},
{
"type": "promptString",
"id": "cloud-org-id",
"description": "Yandex Cloud Organization ID"
},
{
"type": "promptString",
"id": "org-id",
"description": "Yandex Tracker Organization ID (optional)"
}
],
"servers": {
"yandex-tracker": {
"type": "stdio",
"command": "uvx",
"args": ["yandex-tracker-mcp@latest"],
"env": {
"TRACKER_TOKEN": "${input:tracker-token}",
"TRACKER_CLOUD_ORG_ID": "${input:cloud-org-id}",
"TRACKER_ORG_ID": "${input:org-id}",
"TRANSPORT": "stdio"
}
}
}
}

使用 Docker：

{
"inputs": [
{
"type": "promptString",
"id": "tracker-token",
"description": "Yandex Tracker Token",
"password": true
},
{
"type": "promptString",
"id": "cloud-org-id",
"description": "Yandex Cloud Organization ID"
},
{
"type": "promptString",
"id": "org-id",
"description": "Yandex Tracker Organization ID (optional)"
}
],
"servers": {
"yandex-tracker": {
"type": "stdio",
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "TRACKER_TOKEN",
"-e", "TRACKER_CLOUD_ORG_ID",
"-e", "TRACKER_ORG_ID",
"ghcr.io/aikts/yandex-tracker-mcp:latest"
],
"env": {
"TRACKER_TOKEN": "${input:tracker-token}",
"TRACKER_CLOUD_ORG_ID": "${input:cloud-org-id}",
"TRACKER_ORG_ID": "${input:org-id}",
"TRANSPORT": "stdio"
}
}
}
}

选项 2：全局配置

添加到 VS Code 的 settings.json：

使用 uvx：

{
"github.copilot.chat.mcp.servers": {
"yandex-tracker": {
"type": "stdio",
"command": "uvx",
"args": ["yandex-tracker-mcp@latest"],
"env": {
"TRACKER_TOKEN": "your_tracker_token_here",
"TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here",
"TRACKER_ORG_ID": "your_org_id_here"
}
}
}
}

使用 Docker：

{
"github.copilot.chat.mcp.servers": {
"yandex-tracker": {
"type": "stdio",
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "TRACKER_TOKEN",
"-e", "TRACKER_CLOUD_ORG_ID",
"-e", "TRACKER_ORG_ID",
"ghcr.io/aikts/yandex-tracker-mcp:latest"
],
"env": {
"TRACKER_TOKEN": "your_tracker_token_here",
"TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here",
"TRACKER_ORG_ID": "your_org_id_here"
}
}
}
}

其他支持 MCP 的客户端

对于其他支持 MCP 的客户端，使用标准的 MCP 服务器配置格式：

使用 uvx：

{
"mcpServers": {
"yandex-tracker": {
"command": "uvx",
"args": ["yandex-tracker-mcp@latest"],
"env": {
"TRACKER_TOKEN": "your_tracker_token_here",
"TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here",
"TRACKER_ORG_ID": "your_org_id_here"
}
}
}
}

使用 Docker：

{
"mcpServers": {
"yandex-tracker": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "TRACKER_TOKEN",
"-e", "TRACKER_CLOUD_ORG_ID",
"-e", "TRACKER_ORG_ID",
"ghcr.io/aikts/yandex-tracker-mcp:latest"
],
"env": {
"TRACKER_TOKEN": "your_tracker_token_here",
"TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here",
"TRACKER_ORG_ID": "your_org_id_here"
}
}
}
}

重要提示：

请将占位符值替换为你实际的凭证。
配置更改后，请重启你的 AI 客户端。
确保 uvx 已安装并可在系统路径中使用。
对于生产环境，建议使用环境变量而不是硬编码令牌。

💻 使用示例

基础用法

以下是使用不同客户端配置 Yandex Tracker MCP Server 的示例，你可以根据自己的需求选择合适的客户端和配置方式。

高级用法

在实际使用中，你可以根据具体场景灵活组合配置选项，例如结合 OAuth 2.0 身份验证和 Redis 缓存，以实现更高效、安全的使用体验。

📚 详细文档

可用的 MCP 工具

服务器通过 MCP 协议公开了以下工具：

队列管理

queues_get_all：列出所有可用的 Yandex Tracker 队列。
- 返回分页的队列信息。
- 遵循 TRACKER_LIMIT_QUEUES 限制。
queue_get_local_fields：获取特定队列的本地字段。
- 参数：queue_id（字符串，队列键，如 "SOMEPROJECT"）。
- 返回队列特定的自定义字段，包括 ID、名称和键。
- 遵循 TRACKER_LIMIT_QUEUES 限制。
queue_get_tags：获取特定队列的所有标签。
- 参数：queue_id（字符串，队列键，如 "SOMEPROJECT"）。
- 返回指定队列中可用的标签列表。
- 遵循 TRACKER_LIMIT_QUEUES 限制。
queue_get_versions：获取特定队列的所有版本。
- 参数：queue_id（字符串，队列键，如 "SOMEPROJECT"）。
- 返回指定队列中可用的版本列表，包括名称、描述、日期和状态等详细信息。
- 遵循 TRACKER_LIMIT_QUEUES 限制。

用户管理

users_get_all：获取组织中注册的用户账户信息。
- 参数：
  - per_page（可选）：每页的用户数量（默认：50）。
  - page（可选）：要返回的页码（默认：1）。
- 返回分页的用户列表，包含登录名、电子邮件、许可证状态和组织详细信息。
- 包括用户元数据，如外部状态、离职状态和通知偏好。
user_get：通过登录名或用户 ID 获取特定用户的信息。
- 参数：user_id（字符串，用户登录名，如 "john.doe" 或用户 ID，如 "12345"）。
- 返回详细的用户信息，包括登录名、电子邮件、许可证状态和组织详细信息。
- 支持使用用户登录名和数字用户 ID 进行灵活识别。
user_get_current：获取当前经过身份验证的用户信息。
- 无需参数。
- 返回与当前身份验证令牌关联的用户的详细信息。
- 包括经过身份验证的用户的登录名、电子邮件、显示名称和组织详细信息。

字段管理

get_global_fields：获取 Yandex Tracker 中所有可用的全局字段。
- 返回可用于问题的全局字段的完整列表。
- 包括字段架构、类型信息和配置。

状态和类型管理

get_statuses：获取所有可用的问题状态。
- 返回可分配的问题状态的完整列表。
- 包括状态 ID、名称和类型信息。
get_issue_types：获取所有可用的问题类型。
- 返回用于创建/更新问题的问题类型的完整列表。
- 包括类型 ID、名称和配置详细信息。
get_priorities：获取所有可用的问题优先级。
- 返回可分配给问题的优先级的完整列表。
- 包括优先级键、名称和顺序信息。

问题操作

issue_get：按 ID 检索详细的问题信息。
- 参数：
  - issue_id（字符串，格式："QUEUE-123"）。
  - include_description（布尔值，可选，默认：true）：是否在结果中包含问题描述。描述可能很大，仅在需要时使用。
- 返回完整的问题数据，包括状态、负责人、描述等。
issue_get_url：生成问题的网页 URL。
- 参数：issue_id（字符串）。
- 返回：https://tracker.yandex.ru/{issue_id}
issue_get_comments：获取问题的所有评论。
- 参数：issue_id（字符串）。
- 返回按时间顺序排列的评论列表，包含元数据。
issue_get_links：获取相关问题的链接。
- 参数：issue_id（字符串）。
- 返回相关、阻塞或重复问题的链接。
issue_get_worklogs：检索工作日志条目。
- 参数：issue_ids（字符串数组）。
- 返回指定问题的时间跟踪数据。
issue_get_attachments：获取问题的附件。
- 参数：issue_id（字符串，格式："QUEUE-123"）。
- 返回指定问题的附件列表，包含元数据。
issue_get_checklist：获取问题的检查列表项。
- 参数：issue_id（字符串，格式："QUEUE-123"）。
- 返回检查列表项的列表，包括文本、状态、负责人和截止日期信息。

搜索和发现

issues_find：使用 Yandex Tracker 查询语言搜索问题。
- 参数：
  - query（必需）：使用 Yandex Tracker 查询语言语法的查询字符串。
  - include_description（布尔值，可选，默认：false）：是否在问题结果中包含问题描述。描述可能很大，仅在需要时使用。
  - fields（字符串列表，可选）：要包含在响应中的字段。通过选择仅需要的字段，有助于优化上下文窗口的使用。如果未指定，则返回所有可用字段。
  - page（可选）：分页的页码（默认：1）。
  - per_page（可选）：每页的项目数量（默认：100）。如果结果超过上下文窗口，可能会减少该数量。
- 返回每页指定数量的问题。
issues_count：使用 Yandex Tracker 查询语言统计匹配查询的问题数量。
- 参数：
  - query（必需）：使用 Yandex Tracker 查询语言语法的查询字符串。
- 返回符合指定条件的问题总数。
- 支持所有查询语言功能：字段过滤、日期函数、逻辑运算符和复杂表达式。
- 对于分析、报告和了解问题分布很有用，无需检索完整的问题数据。

HTTP 传输

MCP 服务器还可以在可流式 HTTP 模式下运行，适用于基于 Web 的集成或标准输入输出传输不适用的情况。

可流式 HTTP 模式的环境变量

# 必需 - 将传输设置为可流式 HTTP 模式
TRANSPORT=streamable-http

# 服务器配置
HOST=0.0.0.0  # 默认：0.0.0.0（所有接口）
PORT=8000     # 默认：8000

启动可流式 HTTP 服务器

# 基本的可流式 HTTP 服务器启动
TRANSPORT=streamable-http uvx yandex-tracker-mcp@latest

# 使用自定义主机和端口
TRANSPORT=streamable-http \
HOST=localhost \
PORT=9000 \
uvx yandex-tracker-mcp@latest

# 使用所有环境变量
TRANSPORT=streamable-http \
HOST=0.0.0.0 \
PORT=8000 \
TRACKER_TOKEN=your_token \
TRACKER_CLOUD_ORG_ID=your_org_id \
uvx yandex-tracker-mcp@latest

如果在连接到 MCP 服务器时使用以下格式（以 Claude Code 为例），可以跳过配置 TRACKER_CLOUD_ORG_ID 或 TRACKER_ORG_ID：

claude mcp add --transport http yandex-tracker "http://localhost:8000/mcp/?cloudOrgId=your_cloud_org_id&"

或

claude mcp add --transport http yandex-tracker "http://localhost:8000/mcp/?orgId=org_id&"

如果选择使用 OAuth 2.0 身份验证，也可以跳过配置全局 TRACKER_TOKEN 环境，如下文所述。

OAuth 2.0 身份验证

Yandex Tracker MCP Server 支持 OAuth 2.0 身份验证，作为静态 API 令牌的安全替代方案。配置后，服务器充当 OAuth 提供程序，促进 MCP 客户端与 Yandex OAuth 服务之间的身份验证。

OAuth 工作原理

MCP 服务器实现了标准的 OAuth 2.0 授权码流程：

客户端注册：你的 MCP 客户端向服务器注册以获取客户端凭证。
授权：用户被重定向到 Yandex OAuth 进行身份验证。
令牌交换：服务器将授权码交换为访问令牌。
API 访问：客户端使用承载令牌进行所有 API 请求。
令牌刷新：过期的令牌可以在不重新进行身份验证的情况下刷新。

MCP 客户端 → MCP 服务器 → Yandex OAuth → 用户身份验证
↑                                           ↓
└────────── 访问令牌 ←─────────────────┘

OAuth 配置

要启用 OAuth 身份验证，请设置以下环境变量：

# 启用 OAuth 模式
OAUTH_ENABLED=true

# Yandex OAuth 应用凭证（OAuth 必需）
OAUTH_CLIENT_ID=your_yandex_oauth_app_id
OAUTH_CLIENT_SECRET=your_yandex_oauth_app_secret

# MCP 服务器的公共 URL（OAuth 回调必需）
MCP_SERVER_PUBLIC_URL=https://your-mcp-server.example.com

# 可选的 OAuth 设置
OAUTH_SERVER_URL=https://oauth.yandex.ru  # 默认的 Yandex OAuth 服务器

# 启用 OAuth 时，TRACKER_TOKEN 变为可选

设置 Yandex OAuth 应用

访问 Yandex OAuth 并创建一个新应用。
将回调 URL 设置为：{MCP_SERVER_PUBLIC_URL}/oauth/yandex/callback。
请求以下权限：
- tracker:read - Tracker 的读取权限。
- tracker:write - Tracker 的写入权限。
保存你的客户端 ID 和客户端密钥。

OAuth 与静态令牌身份验证对比

特性	OAuth	静态令牌
安全性	具有过期时间的动态令牌	长期有效的静态令牌
用户体验	交互式登录流程	一次性配置
令牌管理	自动刷新	手动轮换
访问控制	按用户进行身份验证	共享令牌
设置复杂度	需要设置 OAuth 应用	简单的令牌配置

OAuth 模式限制

目前，OAuth 模式要求 MCP 服务器可公开访问，以支持回调 URL。
OAuth 模式最适合支持基于 Web 的身份验证流程的交互式客户端。

在 MCP 客户端中使用 OAuth

启用 OAuth 后，MCP 客户端需要：

支持 OAuth 2.0 授权码流程。
在访问令牌过期时处理令牌刷新。
安全地存储刷新令牌，以实现持久身份验证。

注意：并非所有 MCP 客户端目前都支持 OAuth 身份验证。请查看客户端文档，了解 OAuth 兼容性。

Claude Code 的示例配置：

claude mcp add --transport http yandex-tracker https://your-mcp-server.example.com/mcp/ -s user

OAuth 数据存储

MCP 服务器支持两种不同的 OAuth 数据存储后端（客户端注册、访问令牌、刷新令牌和授权状态）：

内存存储（默认）

内存存储将所有 OAuth 数据保存在服务器内存中。这是默认选项，无需额外配置。特点：

持久性：服务器重启时数据丢失。
性能：由于数据存储在内存中，访问速度非常快。
可扩展性：限于单服务器实例。
设置：无需额外依赖。
适用场景：开发、测试或单实例部署，在这些场景中，服务器重启时丢失 OAuth 会话是可以接受的。配置：

OAUTH_STORE=memory  # 默认值，可以省略

Redis 存储

Redis 存储使用 Redis 数据库为 OAuth 数据提供持久存储。这确保 OAuth 会话在服务器重启后仍然存在，并支持多实例部署。特点：

持久性：数据在服务器重启后仍然存在。
性能：访问速度快，但有网络开销。
可扩展性：支持多个服务器实例共享同一个 Redis 数据库。
设置：需要安装和配置 Redis 服务器。
适用场景：生产部署、高可用性设置或需要持久保存 OAuth 会话的场景。配置：

# 启用 Redis 存储用于 OAuth 数据
OAUTH_STORE=redis

# Redis 连接设置（与工具缓存使用的设置相同）
REDIS_ENDPOINT=localhost                  # 默认：localhost
REDIS_PORT=6379                           # 默认：6379
REDIS_DB=0                                # 默认：0
REDIS_PASSWORD=your_redis_password        # 可选：Redis 密码
REDIS_POOL_MAX_SIZE=10                    # 默认：10

存储行为：

客户端信息：持久存储。
OAuth 状态：带有生存时间（TTL）的存储，以提高安全性。
授权码：带有 TTL 的存储，并在使用后自动清理。
访问令牌：根据令牌生命周期自动过期存储。
刷新令牌：持久存储，直到被撤销。
键命名空间：使用 oauth:* 前缀，以避免与其他 Redis 数据冲突。

重要提示：

两种存储都使用与工具缓存系统相同的 Redis 连接设置。
使用 Redis 存储时，确保你的 Redis 实例已正确安全配置并可访问。
OAUTH_STORE 设置仅影响 OAuth 数据存储；工具缓存使用 TOOLS_CACHE_ENABLED。
Redis 存储使用 JSON 序列化，以提高跨语言兼容性和调试便利性。

身份验证

Yandex Tracker MCP Server 支持多种身份验证方法，并具有明确的优先级顺序。服务器将根据以下层次结构使用第一个可用的身份验证方法：

身份验证优先级顺序

动态 OAuth 令牌（最高优先级）

当启用 OAuth 且用户通过 OAuth 流程进行身份验证时。
令牌根据用户会话动态获取和刷新。
必需的环境变量：OAUTH_ENABLED=true、OAUTH_CLIENT_ID、OAUTH_CLIENT_SECRET、MCP_SERVER_PUBLIC_URL。

静态 OAuth 令牌

通过环境变量提供的传统 OAuth 令牌。
所有请求使用单个令牌。
必需的环境变量：TRACKER_TOKEN（你的 OAuth 令牌）。

静态 IAM 令牌

用于服务到服务身份验证的 IAM（身份和访问管理）令牌。
适用于自动化系统和 CI/CD 管道。
必需的环境变量：TRACKER_IAM_TOKEN（你的 IAM 令牌）。

动态 IAM 令牌（最低优先级）

使用服务账户凭证自动检索。
令牌自动获取和刷新。
必需的环境变量：TRACKER_SA_KEY_ID、TRACKER_SA_SERVICE_ACCOUNT_ID、TRACKER_SA_PRIVATE_KEY。

身份验证场景

场景 1：使用动态令牌的 OAuth（推荐用于交互式使用）

# 启用 OAuth 模式
OAUTH_ENABLED=true
OAUTH_CLIENT_ID=your_oauth_app_id
OAUTH_CLIENT_SECRET=your_oauth_app_secret
MCP_SERVER_PUBLIC_URL=https://your-server.com

# 组织 ID（二选一）
TRACKER_CLOUD_ORG_ID=your_cloud_org_id  # 或 TRACKER_ORG_ID

场景 2：静态 OAuth 令牌（简单设置）

# OAuth 令牌
TRACKER_TOKEN=your_oauth_token

# 组织 ID（二选一）
TRACKER_CLOUD_ORG_ID=your_cloud_org_id  # 或 TRACKER_ORG_ID

场景 3：静态 IAM 令牌

# IAM 令牌
TRACKER_IAM_TOKEN=your_iam_token

# 组织 ID（二选一）
TRACKER_CLOUD_ORG_ID=your_cloud_org_id  # 或 TRACKER_ORG_ID

场景 4：使用服务账户的动态 IAM 令牌

# 服务账户凭证
TRACKER_SA_KEY_ID=your_key_id
TRACKER_SA_SERVICE_ACCOUNT_ID=your_service_account_id
TRACKER_SA_PRIVATE_KEY=your_private_key

# 组织 ID（二选一）
TRACKER_CLOUD_ORG_ID=your_cloud_org_id  # 或 TRACKER_ORG_ID

重要提示

服务器按上述顺序检查身份验证方法。
一次仅使用一种身份验证方法。
对于生产环境，建议使用动态令牌（OAuth 或 IAM）以提高安全性。
IAM 令牌的生命周期比 OAuth 令牌短，可能需要更频繁地更新。
使用服务账户时，确保账户对 Yandex Tracker 具有适当的权限。

配置

环境变量

# 身份验证（使用以下方法之一）
# 方法 1：OAuth 令牌
TRACKER_TOKEN=your_yandex_tracker_oauth_token

# 方法 2：IAM 令牌
TRACKER_IAM_TOKEN=your_iam_token

# 方法 3：服务账户（用于动态 IAM 令牌）
TRACKER_SA_KEY_ID=your_key_id                    # 服务账户密钥 ID
TRACKER_SA_SERVICE_ACCOUNT_ID=your_sa_id        # 服务账户 ID
TRACKER_SA_PRIVATE_KEY=your_private_key          # 服务账户私钥

# 组织配置（二选一）
TRACKER_CLOUD_ORG_ID=your_cloud_org_id    # 适用于 Yandex 云组织
TRACKER_ORG_ID=your_org_id                # 适用于 Yandex 360 组织

# API 配置（可选）
TRACKER_API_BASE_URL=https://api.tracker.yandex.net  # 默认：https://api.tracker.yandex.net

# 安全 - 限制对特定队列的访问（可选）
TRACKER_LIMIT_QUEUES=PROJ1,PROJ2,DEV      # 以逗号分隔的队列键

# 服务器配置
HOST=0.0.0.0                              # 默认：0.0.0.0
PORT=8000                                 # 默认：8000
TRANSPORT=stdio                           # 选项：stdio、streamable-http、sse

# Redis 连接设置（用于缓存和 OAuth 存储）
REDIS_ENDPOINT=localhost                  # 默认：localhost
REDIS_PORT=6379                           # 默认：6379
REDIS_DB=0                                # 默认：0
REDIS_PASSWORD=your_redis_password        # 可选：Redis 密码
REDIS_POOL_MAX_SIZE=10                    # 默认：10

# 工具缓存配置（可选）
TOOLS_CACHE_ENABLED=true                  # 默认：false
TOOLS_CACHE_REDIS_TTL=3600                # 默认：3600 秒（1 小时）

# OAuth 2.0 身份验证（可选）
OAUTH_ENABLED=true                        # 默认：false
OAUTH_STORE=redis                         # 选项：memory、redis（默认：memory）
OAUTH_SERVER_URL=https://oauth.yandex.ru  # 默认：https://oauth.yandex.ru
OAUTH_CLIENT_ID=your_oauth_client_id      # 启用 OAuth 时必需
OAUTH_CLIENT_SECRET=your_oauth_secret     # 启用 OAuth 时必需
MCP_SERVER_PUBLIC_URL=https://your.server.com  # 启用 OAuth 时必需
TRACKER_READ_ONLY=true                    # 默认：false - 限制 OAuth 为只读权限

Docker 部署

使用预构建的镜像（推荐）

# 使用环境文件
docker run --env-file .env -p 8000:8000 ghcr.io/aikts/yandex-tracker-mcp:latest

# 使用内联环境变量
docker run -e TRACKER_TOKEN=your_token \
-e TRACKER_CLOUD_ORG_ID=your_org_id \
-p 8000:8000 \
ghcr.io/aikts/yandex-tracker-mcp:latest

本地构建镜像

docker build -t yandex-tracker-mcp .

Docker Compose

使用预构建的镜像

version: '3.8'
services:
mcp-tracker:
image: ghcr.io/aikts/yandex-tracker-mcp:latest
ports:
- "8000:8000"
environment:
- TRACKER_TOKEN=${TRACKER_TOKEN}
- TRACKER_CLOUD_ORG_ID=${TRACKER_CLOUD_ORG_ID}

本地构建

version: '3.8'
services:
mcp-tracker:
build: .
ports:
- "8000:8000"
environment:
- TRACKER_TOKEN=${TRACKER_TOKEN}
- TRACKER_CLOUD_ORG_ID=${TRACKER_CLOUD_ORG_ID}

开发设置

# 克隆并设置
git clone https://github.com/aikts/yandex-tracker-mcp
cd yandex-tracker-mcp

# 安装开发依赖
uv sync --dev

# 格式化和静态检查
make

🔧 技术细节

该项目通过实现 MCP 协议，结合 Yandex Tracker API 的功能，利用多种身份验证和存储机制，为 AI 助手与 Yandex Tracker 的交互提供了全面的支持。在性能方面，通过可选的 Redis 缓存层提高了响应速度；在安全方面，提供了多种身份验证方法和队列访问限制；在可扩展性方面，支持多种传输选项和不同的客户端配置。

📄 许可证

本项目根据 LICENSE 文件中指定的条款进行许可。

支持

如果遇到问题或有疑问：

查看 Yandex Tracker API 文档。
在此处提交问题。

0 条评论
分类：开发

Yandex Tracker Mcp