Yandex Tracker Mcp Server

Yandex Tracker MCP 服务

mcp-name: io.github.aikts/yandex-tracker-mcp

一个功能全面的 Model Context Protocol（MCP）服务，可让 AI 助手与 Yandex Tracker API 交互。该服务提供安全、经过身份验证的方式来访问 Yandex Tracker 的问题、队列、评论、工时记录和搜索功能，并可选择使用 Redis 缓存来提升性能。

此处提供俄语文档 / Документация на русском языке доступна здесь。

功能

• 完整的队列管理：列出并访问所有可用的 Yandex Tracker 队列，支持分页、标签检索和详细元数据
• 项目、组合和目标：为 Tracker「实体」API 中的每种实体类型提供专用的读写工具，并采用明确的架构（通过 TRACKER_ENTITIES_ENABLED 启用）
• 用户管理：检索用户账户信息，包括登录详情、电子邮件地址、许可证状态和组织数据
• 完整的问题生命周期管理：创建、读取、更新和管理问题，支持自定义字段、附件和工作流转换
• 状态工作流管理：执行状态转换、通过解决方案关闭问题，并处理复杂工作流
• 字段管理：访问全局字段、队列专用的本地字段、状态、问题类型、优先级和解决方案
• 看板和冲刺：列出敏捷看板及其冲刺，以查找用于问题规划的冲刺 ID
• 高级查询语言：全面支持 Yandex Tracker 查询语言，包括复杂筛选、排序和日期函数
• 性能缓存：可选的 Redis 缓存层，可缩短响应时间
• 安全控制：可配置队列访问限制并安全处理令牌
• 多种传输选项：支持 stdio、SSE（已弃用）和 HTTP 传输方式，便于灵活集成
• OAuth 2.0 身份验证：支持动态令牌身份验证和自动刷新，可作为静态 API 令牌的替代方案
• 组织支持：兼容标准组织 ID 和云组织 ID

组织 ID 配置

根据你的 Yandex 组织类型选择以下选项之一：

• Yandex Cloud 组织：对于由 Yandex Cloud 管理的组织，请使用 TRACKER_CLOUD_ORG_ID 环境变量
• Yandex 360 组织：对于 Yandex 360 组织，请使用 TRACKER_ORG_ID 环境变量

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

MCP 客户端配置

在 Claude Desktop 中安装扩展

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

安装

1. 从 GitHub Releases 下载 *.mcpb 文件。
2. 双击下载的文件，将其安装到 Claude Desktop 中。
3. 按提示提供你的 Yandex Tracker OAuth 令牌。
4. 确认扩展已启用，即可使用此 MCP 服务。

手动安装

前置条件

• 已在全局安装 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 - 你的 Yandex Cloud 组织 ID
  • TRACKER_ORG_ID - 你的 Yandex 360 组织 ID

设置这两项中的一项即可。若同时设置两项，每次 Tracker 调用都会失败，并显示 Only one of org_id or cloud_org_id should be provided. 以下示例使用 TRACKER_CLOUD_ORG_ID；对于 Yandex 360，请将该键替换为 TRACKER_ORG_ID。

{
  "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"
      }
    }
  }
}

{
  "mcpServers": {
    "yandex-tracker": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "TRACKER_TOKEN",
        "-e", "TRACKER_CLOUD_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"
      }
    }
  }
}

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 TRANSPORT=stdio

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 TRANSPORT=stdio ghcr.io/aikts/yandex-tracker-mcp:latest"

{
  "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"
      }
    }
  }
}

{
  "mcpServers": {
    "yandex-tracker": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "TRACKER_TOKEN",
        "-e", "TRACKER_CLOUD_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"
      }
    }
  }
}

{
  "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"
      }
    }
  }
}

{
  "mcpServers": {
    "yandex-tracker": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "TRACKER_TOKEN",
        "-e", "TRACKER_CLOUD_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"
      }
    }
  }
}

{
  "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"
        }
      }
    }
  }
}

{
  "context_servers": {
    "yandex-tracker": {
      "source": "custom",
      "command": {
        "path": "docker",
        "args": [
          "run", "--rm", "-i",
          "-e", "TRACKER_TOKEN",
          "-e", "TRACKER_CLOUD_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"
        }
      }
    }
  }
}

{
  "inputs": [
    {
      "type": "promptString",
      "id": "tracker-token",
      "description": "Yandex Tracker Token",
      "password": true
    },
    {
      "type": "promptString",
      "id": "cloud-org-id",
      "description": "Yandex Cloud Organization ID"
    }
  ],
  "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}",
        "TRANSPORT": "stdio"
      }
    }
  }
}

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

{
  "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"
      }
    }
  }
}

{
  "github.copilot.chat.mcp.servers": {
    "yandex-tracker": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "TRACKER_TOKEN",
        "-e", "TRACKER_CLOUD_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"
      }
    }
  }
}

{
  "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"
      }
    }
  }
}

{
  "mcpServers": {
    "yandex-tracker": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "TRACKER_TOKEN",
        "-e", "TRACKER_CLOUD_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"
      }
    }
  }
}

重要说明：

• 将占位值替换为你的实际凭据
• 更改配置后，重启 AI 客户端
• 确保已安装 uvx，且其位于系统 PATH 中
• 用于生产环境时，建议使用环境变量，而不是将令牌硬编码

可用的 MCP 工具

该服务通过 MCP 协议提供以下工具：

http 传输

MCP 服务也可以以 streamable-http 模式运行，用于 Web 集成，或在不适合使用 stdio 传输时运行。

streamable-http 模式环境变量

# Required - Set transport to streamable-http mode
TRANSPORT=streamable-http

# Server Configuration
HOST=0.0.0.0  # Default: 0.0.0.0 (all interfaces)
PORT=8000     # Default: 8000

启动 streamable-http 服务

# Basic streamable-http server startup
TRANSPORT=streamable-http uvx yandex-tracker-mcp@latest

# With custom host and port
TRANSPORT=streamable-http \
HOST=localhost \
PORT=9000 \
uvx yandex-tracker-mcp@latest

# With all environment variables
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 服务时使用以下格式，则可以跳过配置 TRACKER_CLOUD_ORG_ID 或 TRACKER_ORG_ID（以下是 Claude Code 的示例）：

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 授权码流程：

1. 客户端注册： MCP 客户端向服务注册，以获取客户端凭据
2. 授权： 用户会被重定向到 Yandex OAuth 进行身份验证
3. 令牌交换： 服务将授权码交换为访问令牌
4. API 访问： 客户端使用 Bearer 令牌发送所有 API 请求
5. 令牌刷新： 无需重新进行身份验证，即可刷新过期令牌

MCP Client → MCP Server → Yandex OAuth → User Authentication
    ↑                                           ↓
    └────────── Access Token ←─────────────────┘

OAuth 配置

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

# Enable OAuth mode
OAUTH_ENABLED=true

# Yandex OAuth Application Credentials (required for OAuth)
OAUTH_CLIENT_ID=your_yandex_oauth_app_id
OAUTH_CLIENT_SECRET=your_yandex_oauth_app_secret

# Public URL of your MCP server (required for OAuth callbacks)
MCP_SERVER_PUBLIC_URL=https://your-mcp-server.example.com

# Optional OAuth settings
OAUTH_SERVER_URL=https://oauth.yandex.ru  # Default Yandex OAuth server

# When OAuth is enabled, TRACKER_TOKEN becomes optional

OAuth 范围

启用 OAUTH_USE_SCOPES=true（默认值）时，服务会请求、声明并要求 Yandex Tracker 范围 tracker:read 和 tracker:write；如果设置了 TRACKER_READ_ONLY=true，则只要求 tracker:read，因此只读实例不会向用户请求写入权限。设置 OAUTH_USE_SCOPES=false 会完全从流程中移除范围，这是 Yandex Cloud 联合身份验证所要求的。

设置 Yandex OAuth 应用

1. 前往 Yandex OAuth 并创建新应用
2. 将回调 URL 设置为：{MCP_SERVER_PUBLIC_URL}/oauth/yandex/callback
3. 请求以下权限：
   • tracker:read - Tracker 的读取权限
   • tracker:write - Tracker 的写入权限
4. 保存 Client ID 和 Client Secret

OAuth 与静态令牌身份验证

OAuth 模式的限制

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

在 MCP 客户端中使用 OAuth

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

1. 支持 OAuth 2.0 授权码流程
2. 在访问令牌过期时处理令牌刷新
3. 安全存储刷新令牌，以便持续进行身份验证

注意：目前并非所有 MCP 客户端都支持 OAuth 身份验证。请查看客户端文档，确认其是否兼容 OAuth。

Claude Code 的配置示例：

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

OAuth 数据存储

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

InMemory 存储（默认）

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

特点：

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

配置：

OAUTH_STORE=memory  # Default value, can be omitted

Redis 存储

Redis 存储使用 Redis 数据库持久保存 OAuth 数据。这可确保 OAuth 会话在服务重启后仍然有效，并支持多实例部署。

特点：

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

配置：

# Enable Redis store for OAuth data
OAUTH_STORE=redis

# Redis connection settings (same as used for tools caching)
REDIS_ENDPOINT=localhost                  # Default: localhost
REDIS_PORT=6379                           # Default: 6379
REDIS_DB=0                                # Default: 0
REDIS_PASSWORD=your_redis_password        # Optional: Redis password
REDIS_POOL_MAX_SIZE=10                    # Default: 10

存储行为：

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

令牌加密（Redis 存储必需）

使用 Redis 存储时，必须配置加密，以保护静态存储的 OAuth 令牌。令牌值使用 Fernet（AES-128）加密，Redis 键使用 SHA-256 哈希，而非原始令牌，从而防止 Redis 遭到入侵时令牌泄露。

生成加密密钥：

python3 -c "import base64, os; print(base64.b64encode(os.urandom(32)).decode())"

配置：

# Single encryption key
OAUTH_ENCRYPTION_KEYS=<base64-encoded-32-byte-key>

# Multiple keys for rotation (first encrypts, all decrypt)
OAUTH_ENCRYPTION_KEYS=<new-key>,<old-key>

密钥轮换可无缝更新密钥：先添加新密钥，等待旧令牌过期，然后移除旧密钥。

重要说明：

• 两种存储均使用与工具缓存系统相同的 Redis 连接设置
• 使用 Redis 存储时，请确保 Redis 实例已妥善保护且可访问
• OAUTH_STORE 设置仅影响 OAuth 数据存储；工具缓存使用 TOOLS_CACHE_ENABLED
• Redis 存储使用 JSON 序列化，以提高跨语言兼容性并便于调试

身份验证

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

身份验证优先级顺序

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

   • 启用 OAuth 后，用户通过 OAuth 流程完成身份验证时使用
   • 按用户会话动态获取并刷新令牌
   • 同时支持标准 Yandex OAuth 和 Yandex Cloud 联合 OAuth
   • 必需的环境变量：OAUTH_ENABLED=true、OAUTH_CLIENT_ID、OAUTH_CLIENT_SECRET、MCP_SERVER_PUBLIC_URL
   • 联合 OAuth 的其他变量：OAUTH_SERVER_URL=https://auth.yandex.cloud/oauth、OAUTH_TOKEN_TYPE=Bearer、OAUTH_USE_SCOPES=false

2. 透传 Bearer OAuth 令牌

   • MCP OAuth 中间件未提供令牌时，服务器可以从传入的 Authorization: Bearer <token> 标头中读取 Yandex OAuth 令牌
   • 适用于部署在受信任的反向代理或网关之后的场景：该代理或网关负责验证用户身份、查找用户存储的 Yandex OAuth 令牌，并在每个请求中注入该令牌
   • 启用并激活 OAuth 模式时，MCP OAuth 令牌仍具有更高优先级

3. 静态 OAuth 令牌

   • 通过环境变量提供的传统 OAuth 令牌
   • 所有请求共用同一个令牌
   • 必需的环境变量：TRACKER_TOKEN（你的 OAuth 令牌）

4. 静态 IAM 令牌

   • 用于服务间身份验证的 IAM（Identity and Access Management）令牌
   • 适用于自动化系统和 CI/CD 流水线
   • 必需的环境变量：TRACKER_IAM_TOKEN（你的 IAM 令牌）

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

   • 使用服务账号凭据自动获取
   • 自动获取并刷新令牌
   • 必需的环境变量：TRACKER_SA_KEY_ID、TRACKER_SA_SERVICE_ACCOUNT_ID、TRACKER_SA_PRIVATE_KEY

身份验证场景

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

# Enable OAuth mode
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

# Organization ID (choose one)
TRACKER_CLOUD_ORG_ID=your_cloud_org_id  # or TRACKER_ORG_ID

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

# OAuth token
TRACKER_TOKEN=your_oauth_token

# Organization ID (choose one)
TRACKER_CLOUD_ORG_ID=your_cloud_org_id  # or TRACKER_ORG_ID

场景 3：反向代理后的透传 Bearer 令牌

当受信任的网关负责验证用户身份、查找用户的 Yandex OAuth 令牌，并在请求标头中携带该令牌转发请求至 MCP 服务时，请使用此模式：

Authorization: Bearer <user_yandex_oauth_token>

# Organization ID (choose one)
TRACKER_CLOUD_ORG_ID=your_cloud_org_id  # or TRACKER_ORG_ID

只有在 MCP OAuth 中间件未为请求提供访问令牌时，才会使用此透传令牌。在启用 OAuth 且 MCP OAuth 会话处于激活状态的部署中，MCP OAuth 令牌优先。

场景 4：静态 IAM 令牌

# IAM token
TRACKER_IAM_TOKEN=your_iam_token

# Organization ID (choose one)
TRACKER_CLOUD_ORG_ID=your_cloud_org_id  # or TRACKER_ORG_ID

场景 5：使用服务账号的动态 IAM 令牌

# Service account credentials
TRACKER_SA_KEY_ID=your_key_id
TRACKER_SA_SERVICE_ACCOUNT_ID=your_service_account_id
TRACKER_SA_PRIVATE_KEY=your_private_key

# Organization ID (choose one)
TRACKER_CLOUD_ORG_ID=your_cloud_org_id  # or TRACKER_ORG_ID

场景 6：OIDC 应用的联邦 OAuth（高级）

# Enable OAuth with Yandex Cloud federation
OAUTH_ENABLED=true
OAUTH_SERVER_URL=https://auth.yandex.cloud/oauth
OAUTH_TOKEN_TYPE=Bearer
OAUTH_USE_SCOPES=false
OAUTH_CLIENT_ID=your_oidc_client_id
OAUTH_CLIENT_SECRET=your_oidc_client_secret
MCP_SERVER_PUBLIC_URL=https://your-server.com

# Organization ID (choose one)
TRACKER_CLOUD_ORG_ID=your_cloud_org_id  # or TRACKER_ORG_ID

此配置支持通过 Yandex Cloud OIDC 应用进行身份验证，这是 Yandex Cloud 中使用联邦账户所必需的。联邦用户通过其组织的身份提供商（IdP）进行身份验证，并使用此 OAuth 流程访问 Yandex Tracker API。

重要说明

• 服务会按上述顺序检查身份验证方式
• 一次仅使用一种身份验证方式
• 在生产环境中，建议使用动态令牌（OAuth 或 IAM）以提高安全性
• IAM 令牌的有效期比 OAuth 令牌短，可能需要更频繁地续期
• 使用服务账户时，请确保该账户拥有适当的 Yandex Tracker 权限

配置

环境变量

# Authentication (use one of the following methods)
# Method 1: OAuth Token
TRACKER_TOKEN=your_yandex_tracker_oauth_token

# Method 2: IAM Token
TRACKER_IAM_TOKEN=your_iam_token

# Method 3: Service Account (for dynamic IAM token)
TRACKER_SA_KEY_ID=your_key_id                    # Service account key ID
TRACKER_SA_SERVICE_ACCOUNT_ID=your_sa_id        # Service account ID
TRACKER_SA_PRIVATE_KEY=your_private_key          # Service account private key

# Organization Configuration (set exactly one - setting both is an error)
TRACKER_CLOUD_ORG_ID=your_cloud_org_id    # For Yandex Cloud organizations
TRACKER_ORG_ID=your_org_id                # For Yandex 360 organizations

# API Configuration (optional)
TRACKER_API_BASE_URL=https://api.tracker.yandex.net  # Default: https://api.tracker.yandex.net
TRACKER_API_TIMEOUT=10                    # Default: 10 - Per-request timeout in seconds for Tracker API calls

# Security - Restrict access to specific queues (optional)
TRACKER_LIMIT_QUEUES=PROJ1,PROJ2,DEV      # Comma-separated queue keys - allow-list of accessible queues
TRACKER_READ_ONLY_QUEUES=PROJ2            # Comma-separated queue keys - allowed for reads but reject writes (per-queue read-only)
TRACKER_ENTITIES_ENABLED=true             # Default: false - Register project/portfolio/goal tools (NOT covered by the queue restrictions above)

# Server Configuration
HOST=0.0.0.0                              # Default: 0.0.0.0
PORT=8000                                 # Default: 8000
TRANSPORT=stdio                           # Options: stdio, streamable-http, sse

# Redis connection settings (used for caching and OAuth store)
REDIS_ENDPOINT=localhost                  # Default: localhost
REDIS_PORT=6379                           # Default: 6379
REDIS_DB=0                                # Default: 0
REDIS_PASSWORD=your_redis_password        # Optional: Redis password
REDIS_POOL_MAX_SIZE=10                    # Default: 10

# Tools caching configuration (optional)
TOOLS_CACHE_ENABLED=true                  # Default: false
TOOLS_CACHE_REDIS_TTL=3600                # Default: 3600 seconds (1 hour)

# OAuth 2.0 Authentication (optional)
OAUTH_ENABLED=true                        # Default: false
OAUTH_STORE=redis                         # Options: memory, redis (default: memory)
OAUTH_SERVER_URL=https://oauth.yandex.ru  # Default: https://oauth.yandex.ru (use https://auth.yandex.cloud/oauth for federation)
OAUTH_TOKEN_TYPE=<Bearer|OAuth|<empty>>   # Default: <empty> (required to be Bearer for Yandex Cloud federation)
OAUTH_USE_SCOPES=true                     # Default: true (set to false for Yandex Cloud federation)
OAUTH_CLIENT_ID=your_oauth_client_id      # Required when OAuth enabled
OAUTH_CLIENT_SECRET=your_oauth_secret     # Required when OAuth enabled
MCP_SERVER_PUBLIC_URL=https://your.server.com  # Required when OAuth enabled
TRACKER_READ_ONLY=true                    # Default: false - Disable all write tools for the whole instance

队列访问控制

队列访问权限可分为三个层级进行限制，从粗粒度到细粒度：

• TRACKER_LIMIT_QUEUES — 队列键的允许列表。列表之外的队列在读取和写入时均视为未找到／不允许。匹配时不区分大小写，此规则同样适用于 TRACKER_READ_ONLY_QUEUES，因此 dev 和 DEV 指的是同一个队列。唯一例外是看板工具：看板属于组织而非队列，因此不会受到筛选，且其设置中可以指定受限队列。
• TRACKER_READ_ONLY — 设为 true 时，所有写入工具都会被注销，因此整个实例为只读。
• TRACKER_READ_ONLY_QUEUES — 按队列设置的只读允许列表。写入工具仍会注册，但任何针对列表中队列的修改调用（创建／更新／移动／评论／工时记录／关联、队列版本创建）都会被拒绝，而读取仍可正常进行。此列表之外的队列仍可读写。

项目／项目组合／目标工具不受此模型约束。 项目、项目组合或目标无法可靠地映射到单个队列，因此上述三项设置都不会限制它们——既不限制读取工具（project_get、project_find、*_get_comments 等），也不限制写入工具（包括评论和清单工具）。启用这些工具后，任何能够访问服务的人都可访问组织范围内的这些实体。因此，这些工具默认不启用：仅当 TRACKER_ENTITIES_ENABLED=true（默认值为 false）时才会注册。对于不需要这些工具的部署，这也能缩减工具清单。TRACKER_READ_ONLY 仍然有效：它会与其他所有写入工具一并注销实体写入工具。

这样，单个实例就能同时对部分队列开放读写权限、对其他队列设置只读权限——例如，将 TRACKER_LIMIT_QUEUES=DEV,MGMT 与 TRACKER_READ_ONLY_QUEUES=MGMT 配合使用，即可完全访问 DEV，并以只读方式查看 MGMT。这对共享 MCP 网关尤其有用：最终用户只能通过服务访问 Tracker，不会直接持有原始令牌。

这些检查是进程内的防护措施。对于直接持有原始 Tracker 令牌的客户端，还应在令牌本身上设置实际限制。

Docker 部署

使用预构建镜像（推荐）

镜像默认使用 TRANSPORT=stdio，通过容器的标准输入／输出进行通信，且不会开放端口。对于下方通过 HTTP 访问服务的示例，请设置 TRANSPORT=streamable-http；对于 stdio 客户端，则使用 -i 运行容器且不添加 -p（参见 MCP 客户端配置示例）。

# Using environment file (it must set TRANSPORT=streamable-http)
docker run --env-file .env -p 8000:8000 ghcr.io/aikts/yandex-tracker-mcp:latest

# With inline environment variables
docker run -e TRACKER_TOKEN=your_token \
           -e TRACKER_CLOUD_ORG_ID=your_org_id \
           -e TRANSPORT=streamable-http \
           -p 8000:8000 \
           ghcr.io/aikts/yandex-tracker-mcp:latest

在本地构建镜像

docker build -t yandex-tracker-mcp .

Docker Compose

使用预构建镜像：

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}
      - TRANSPORT=streamable-http

在本地构建：

services:
  mcp-tracker:
    build: .
    ports:
      - "8000:8000"
    environment:
      - TRACKER_TOKEN=${TRACKER_TOKEN}
      - TRACKER_CLOUD_ORG_ID=${TRACKER_CLOUD_ORG_ID}
      - TRANSPORT=streamable-http

开发环境设置

# Clone and setup
git clone https://github.com/aikts/yandex-tracker-mcp
cd yandex-tracker-mcp

# Install development dependencies
uv sync --dev

# Formatting and static checking
task

许可证

本项目依据 LICENSE 文件中规定的条款进行授权。

支持

如有问题或疑问：

• 查看 Yandex Tracker API 文档
• 在 https://github.com/aikts/yandex-tracker-mcp/issues 提交问题