内容
# Yandex Tracker MCP 服务器
mcp-name: io.github.aikts/yandex-tracker-mcp
一个全面的模型上下文协议（MCP）服务器，使 AI 助手能够与 Yandex Tracker API 交互。该服务器为 Yandex Tracker 问题、队列、评论、工作日志和搜索功能提供安全、身份验证的访问，并可选地使用 Redis 缓存以提高性能。
<a href="https://glama.ai/mcp/servers/@aikts/yandex-tracker-mcp">
<img width="380" height="200" src="https://glama.ai/mcp/servers/@aikts/yandex-tracker-mcp/badge" />
</a>
俄语文档请参见 [此处](README_ru.md)。
## 功能
- **完整的队列管理**：列出和访问所有可用的 Yandex Tracker 队列，支持分页、标签检索和详细的元数据
- **用户管理**：检索用户信息，包括登录详细信息、电子邮件地址、许可证状态和组织数据
- **完整的问题生命周期**：创建、读取、更新和管理问题，支持自定义字段、附件和工作流转换
- **状态工作流管理**：执行状态转换、关闭问题和解决复杂工作流
- **字段管理**：访问全局字段、队列特定的本地字段、状态、问题类型、优先级和解决方案
- **高级查询语言**：完全支持 Yandex Tracker 查询语言，具有复杂的过滤、排序和日期函数
- **性能缓存**：可选的 Redis 缓存层，用于提高响应时间
- **安全控制**：可配置的队列访问限制和安全的令牌处理
- **多种传输选项**：支持 stdio、SSE（已弃用）和 HTTP 传输，以实现灵活的集成
- **OAuth 2.0 身份验证**：基于令牌的动态身份验证，支持自动刷新，作为静态 API 令牌的替代方案
- **组织支持**：兼容标准和云组织 ID
### 组织 ID 配置
根据您的 Yandex 组织类型，选择以下之一：
- **Yandex Cloud 组织**：使用 `TRACKER_CLOUD_ORG_ID` 环境变量，后面用于 Yandex Cloud 管理的组织
- **Yandex 360 组织**：使用 `TRACKER_ORG_ID` 环境变量，后面用于 Yandex 360 组织
您可以在 Yandex Tracker URL 或组织设置中找到组织 ID。
## MCP 客户端配置
### 在 Claude Desktop 上安装扩展
Yandex Tracker MCP 服务器可以作为扩展程序一键安装在 Claude Desktop 上。
#### 安装
1. 从 [GitHub Releases](https://github.com/aikts/yandex-tracker-mcp/releases/latest) 下载 `*.mcpb` 文件。
2. 双击下载的文件以在 Claude Desktop 上安装。 
3. 在提示时提供您的 Yandex Tracker OAuth 令牌。 
4. 确保扩展程序已启用 - 现在您可以使用此 MCP 服务器。
### 手动安装
#### 要求
- [uv](https://docs.astral.sh/uv/getting-started/installation/) 已全局安装
- 有效的 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 Cloud（或 Yandex 360）组织 ID
<details>
<summary><strong>Claude Desktop</strong></summary>
**配置文件路径：**
- macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows：`%APPDATA%\Claude\claude_desktop_config.json`
**使用 uvx：**
```json
{
"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：**
```json
{
"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"
}
}
}
}
```
</details>
<details>
<summary><strong>Claude Code</strong></summary>
**使用 uvx：**
```bash
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：**
```bash
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"
```
</details>
<details>
<summary><strong>Cursor</strong></summary>
**配置文件路径：**
- 项目特定：`./cursor/mcp.json` 在您的项目目录中
- 全局：`~/.cursor/mcp.json`
**使用 uvx：**
```json
{
"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：**
```json
{
"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"
}
}
}
}
```
</details>
<details>
<summary><strong>Windsurf</strong></summary>
**配置文件路径：**
- `~/.codeium/windsurf/mcp_config.json`
访问方式：Windsurf 设置 → Cascade 选项卡 → 模型上下文协议（MCP）服务器 → “查看原始配置”
**使用 uvx：**
```json
{
"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：**
```json
{
"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"
}
}
}
}
```
</details>
<details>
<summary><strong>Zed</strong></summary>
**配置文件路径：**
- `~/.config/zed/settings.json`
访问方式：`Cmd+,`（macOS）或 `Ctrl+,`（Linux/Windows）或命令调色板：“zed: 打开设置”
**注意：** 需要 Zed 预览版以支持 MCP。
**使用 uvx：**
```json
{
"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：**
```json
{
"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"
}
}
}
}
}
```
</details>
<details>
<summary><strong>GitHub Copilot（VS Code）</strong></summary>
**配置文件路径：**
- 工作区：`./vscode/mcp.json` 在您的项目目录中
- 全局：VS Code `settings.json`
**选项 1：工作区配置（推荐用于安全）**
创建 `.vscode/mcp.json`：
**使用 uvx：**
```json
{
"inputs": [
{
"type": "promptString",
"id": "tracker-token",
"description": "Yandex Tracker 令牌",
"password": true
},
{
"type": "promptString",
"id": "cloud-org-id",
"description": "Yandex Cloud 组织 ID"
},
{
"type": "promptString",
"id": "org-id",
"description": "Yandex Tracker 组织 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}",
"TRACKER_ORG_ID": "${input:org-id}",
"TRANSPORT": "stdio"
}
}
}
}
```
**使用 Docker：**
```json
{
"inputs": [
{
"type": "promptString",
"id": "tracker-token",
"description": "Yandex Tracker 令牌",
"password": true
},
{
"type": "promptString",
"id": "cloud-org-id",
"description": "Yandex Cloud 组织 ID"
},
{
"type": "promptString",
"id": "org-id",
"description": "Yandex Tracker 组织 ID（可选）"
}
],
"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：**
```json
{
"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：**
```json
{
"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"
}
}
}
}
```
</details>
<details>
<summary><strong>其他 MCP 兼容客户端</strong></summary>
对于其他 MCP 兼容客户端，请使用标准 MCP 服务器配置格式：
**使用 uvx：**
```json
{
"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：**
```json
{
"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"
}
}
}
}
```
</details>
**重要注意事项：**
- 用实际凭证替换占位符值
- 配置更改后重启 AI 客户端
- 确保 `uvx` 已安装并在您的系统路径中可用
- 在生产环境中，请考虑使用环境变量而不是硬编码令牌
## 可用的 MCP 工具
服务器公开了一组紧凑的基于操作的工具集。每个工具都接受一个 `action` 参数，以便 LLM 客户端看到一个工具，而不是 3-6 个近似重复的工具。写入操作在 `TRACKER_READ_ONLY=true` 时会被拒绝。
有关权威的操作列表、所需参数和返回形状，请调用运行服务器上的 `list_tools` - 每个工具的描述都内联记录了它的操作。
### 问题
- `issue_get` — 按键读取单个问题
- `issue_get_url` — 从问题 ID 构建 Tracker 网络 URL
- `issues_find` — 使用 `query` / 结构化 `filter` / `keys` 和排序的 YQL 搜索
- `issues_count` — YQL 匹配计数
- `issue_get_transitions` — 列出从当前状态可用的状态转换
- `issue_create` / `issue_update` / `issue_close` / `issue_execute_transition` — 写入路径
- `issue_move_to_queue` — 将问题移动到另一个队列
- `issue_comments(action=get/add/update/delete)`
- `issue_links(action=get/add/delete)`
- `issue_worklogs(action=get/add/update/delete)`
- `issue_attachments(action=get/upload/download/delete)`
- `issue_checklist(action=get/add/update/delete/clear)`
- `issue_tags(action=add/remove)`
### 队列和参考数据
- `queues(action=list/tags/versions/fields/metadata/create)`
- `tracker_reference(kind=global_fields/statuses/issue_types/priorities/resolutions)`
### 看板，冲刺，敏捷
- `boards(action=list/get/columns/sprints/create/update/delete)`
- `board_columns(action=create/update/delete)`
- `sprints(action=get/create/update/delete/start/finish)`
### 实体和保存的视图
- `components(action=list/get/create/update/delete)`
- `filters(action=list/get/create/update/delete)`
- `dashboards(action=list/get/widgets/create/update/delete)`
### 自动化
- `triggers(action=list/get/create/update/delete)`
- `autoactions(action=list/get/create/update/delete)`
- `macros(action=list/get/create/update/delete)`
- `workflows(action=list/get_queue)`
### 用户
- `users(action=list/search/get/current)`
### 项目/投资组合/目标
- `projects_search`，`portfolios_search`，`goals_search`，`projects_legacy_list`
- `entity_get` / `entity_create` / `entity_update` / `entity_delete`
### 批量操作
- `bulk(action=update/move/transition/status)`
## HTTP 传输
MCP 服务器也可以在可流式传输的 HTTP 模式下运行，以实现基于 Web 的集成或在_stdio传输不合适时使用。
### 流式 HTTP 模式环境变量
```env
# 必需 - 将传输设置为流式 HTTP 模式
TRANSPORT=streamable-http
# 服务器配置
HOST=0.0.0.0 # 默认：0.0.0.0（所有接口）
PORT=8000 # 默认：8000
```
### 启动流式 HTTP 服务器
```bash
# 基本流式 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 服务器时省略配置 `TRACKER_CLOUD_ORG_ID` 或 `TRACKER_ORG_ID`（示例适用于 Claude Code）：
```bash
claude mcp add --transport http yandex-tracker "http://localhost:8000/mcp/?cloudOrgId=your_cloud_org_id&"
```
或
```bash
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 服务器支持 OAuth 2.0 身份验证，作为静态 API 令牌的安全替代方案。当配置完成后，服务器充当 OAuth 提供者，促进 MCP 客户端与 Yandex OAuth 服务之间的身份验证。
#### OAuth 工作原理
MCP 服务器实现了标准的 OAuth 2.0 授权码流程：
1. **客户端注册**：您的 MCP 客户端向服务器注册以获取客户端凭证
2. **授权**：用户被重定向到 Yandex OAuth 进行身份验证
3. **令牌交换**：服务器将授权码交换为访问令牌
4. **API 访问**：客户端使用持有者令牌进行所有 API 请求
5. **令牌刷新**：过期的令牌可以在无需重新身份验证的情况下刷新
```
MCP 客户端 → MCP 服务器 → Yandex OAuth → 用户身份验证
↑ ↓
└────────── 访问令牌 ←─────────────────┘
```
#### OAuth 配置
要启用 OAuth 身份验证，请设置以下环境变量：
```env
# 启用 OAuth 模式
OAUTH_ENABLED=true
# Yandex OAuth 应用程序凭证（OAuth 所需）
OAUTH_CLIENT_ID=您的_yandex_oauth_应用程序_id
OAUTH_CLIENT_SECRET=您的_yandex_oauth_应用程序_密钥
# 您的 MCP 服务器的公共 URL（OAuth 回调所需）
MCP_SERVER_PUBLIC_URL=https://您的-mcp-服务器.example.com
# 可选的 OAuth 设置
OAUTH_SERVER_URL=https://oauth.yandex.ru # 默认的 Yandex OAuth 服务器
# 启用 OAuth 时，TRACKER_TOKEN 成为可选
```
#### 设置 Yandex OAuth 应用程序
1. 前往 [Yandex OAuth](https://oauth.yandex.ru/) 并创建一个新应用程序
2. 将回调 URL 设置为：`{MCP_SERVER_PUBLIC_URL}/oauth/yandex/callback`
3. 请求以下权限：
- `tracker:read` - Tracker 的读取权限
- `tracker:write` - Tracker 的写入权限
4. 保存您的客户端 ID 和客户端密钥
#### OAuth 与静态令牌身份验证
| 功能 | OAuth | 静态令牌 |
|------------------|--------------------------------|----------------------------|
| 安全性 | 具有过期时间的动态令牌 | 长期静态令牌 |
| 用户体验 | 交互式登录流程 | 一次性配置 |
| 令牌管理 | 自动刷新 | 手动轮换 |
| 访问控制 | 按用户身份验证 | 共享令牌 |
| 设置复杂度 | 需要 OAuth 应用程序设置 | 简单的令牌配置 |
#### OAuth 模式限制
- 目前，OAuth 模式要求 MCP 服务器对于回调 URL 来说是公开可访问的
- OAuth 模式最适合于支持基于 Web 的身份验证流程的交互式客户端
#### 在 MCP 客户端中使用 OAuth
启用 OAuth 后，MCP 客户端需要：
1. 支持 OAuth 2.0 授权码流程
2. 在访问令牌过期时处理令牌刷新
3. 安全地存储刷新令牌以实现持久身份验证
**注意**：并非所有 MCP 客户端当前都支持 OAuth 身份验证。请查看您客户端的文档以获取 OAuth 兼容性信息。
Claude Code 的示例配置：
```bash
claude mcp add --transport http yandex-tracker https://您的-mcp-服务器.example.com/mcp/ -s user
```
#### OAuth 数据存储
MCP 服务器支持两种不同的 OAuth 数据存储后端（客户端注册、访问令牌、刷新令牌和授权状态）：
##### 内存存储（默认）
内存存储将所有 OAuth 数据存储在服务器内存中。这是默认选项，不需要额外的配置。
**特性：**
- **持久性**：服务器重启时数据丢失
- **性能**：由于数据存储在内存中，因此访问速度非常快
- **可扩展性**：仅限于单个服务器实例
- **设置**：不需要额外的依赖项
- **最佳适用场景**：开发、测试或单实例部署，在这些场景中重启时丢失 OAuth 会话是可以接受的
**配置：**
```env
OAUTH_STORE=memory # 默认值，可以省略
```
##### Redis 存储
Redis 存储使用 Redis 数据库为 OAuth 数据提供持久存储。这确保了 OAuth 会话在服务器重启时存活，并且支持多实例部署。
**特性：**
- **持久性**：数据在服务器重启后仍然存在
- **性能**：具有网络开销的快速访问
- **可扩展性**：支持多个服务器实例共享同一个 Redis 数据库
- **设置**：需要安装和配置 Redis 服务器
- **最佳适用场景**：生产部署、高可用性设置或当 OAuth 会话必须持续存在
**配置：**
```env
# 为 OAuth 数据启用 Redis 存储
OAUTH_STORE=redis
# Redis 连接设置（与工具缓存使用的设置相同）
REDIS_ENDPOINT=localhost # 默认：localhost
REDIS_PORT=6379 # 默认：6379
REDIS_DB=0 # 默认：0
REDIS_PASSWORD=您的_redis_密码 # 可选：Redis 密码
REDIS_POOL_MAX_SIZE=10 # 默认：10
```
**存储行为：**
- **客户端信息**：持久存储
- **OAuth 状态**：存储带有 TTL（生存时间）以确保安全
- **授权码**：存储带有 TTL，并在使用后自动清理
- **访问令牌**：存储带有根据令牌寿命的自动过期
- **刷新令牌**：持久存储直到撤销
- **密钥命名空间**：使用 `oauth:*` 前缀以避免与其他 Redis 数据冲突
##### 令牌加密（Redis 存储所需）
使用 Redis 存储时，您必须配置加密以保护静态的 OAuth 令牌。令牌值使用 Fernet（AES-128）加密，Redis 密钥使用 SHA-256 哈希而不是原始令牌，以防止 Redis 泄露时令牌暴露。
**生成加密密钥：**
```bash
python3 -c "import base64, os; print(base64.b64encode(os.urandom(32)).decode())"
```
**配置：**
```env
# 单个加密密钥
OAUTH_ENCRYPTION_KEYS=<base64 编码的 32 字节密钥>
# 多个密钥用于轮换（第一个加密，全部解密）
OAUTH_ENCRYPTION_KEYS=<新密钥>,<旧密钥>
```
密钥轮换允许无缝更新密钥：添加新密钥，等待旧令牌过期，然后删除旧密钥。
**重要注意事项：**
- 两个存储都使用与工具缓存系统相同的 Redis 连接设置
- 使用 Redis 存储时，请确保您的 Redis 实例已正确保护且可访问
- `OAUTH_STORE` 设置仅影响 OAuth 数据存储；工具缓存使用 `TOOLS_CACHE_ENABLED`
- Redis 存储使用 JSON 序列化以实现更好的跨语言兼容性和调试
## 身份验证
Yandex Tracker MCP 服务器支持多种身份验证方法，具有明确的优先级顺序。服务器将根据此层次结构使用第一个可用的身份验证方法：
### 身份验证优先级顺序
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. **静态 OAuth 令牌**
- 通过环境变量提供的传统 OAuth 令牌
- 单个令牌用于所有请求
- 需要环境变量：`TRACKER_TOKEN`（您的 OAuth 令牌）
3. **静态 IAM 令牌**
- 用于服务间身份验证的 IAM（身份和访问管理）令牌
- 适用于自动化系统和 CI/CD 管道
- 需要环境变量：`TRACKER_IAM_TOKEN`（您的 IAM 令牌）
4. **动态 IAM 令牌**（最低优先级）
- 使用服务帐户凭证自动检索
- 令牌自动获取和刷新
- 需要环境变量：`TRACKER_SA_KEY_ID`，`TRACKER_SA_SERVICE_ACCOUNT_ID`，`TRACKER_SA_PRIVATE_KEY`
### 身份验证场景
#### 场景 1：使用动态令牌的 OAuth（推荐用于交互式使用）
```env
# 启用 OAuth 模式
OAUTH_ENABLED=true
OAUTH_CLIENT_ID=您的_oauth_应用程序_id
OAUTH_CLIENT_SECRET=您的_oauth_应用程序_密钥
MCP_SERVER_PUBLIC_URL=https://您的-服务器.com
# 组织 ID（选择一个）
TRACKER_CLOUD_ORG_ID=您的_cloud_org_id # 或 TRACKER_ORG_ID
```
#### 场景 2：静态 OAuth 令牌（简单设置）
```env
# OAuth 令牌
TRACKER_TOKEN=您的_oauth_令牌
# 组织 ID（选择一个）
TRACKER_CLOUD_ORG_ID=您的_cloud_org_id # 或 TRACKER_ORG_ID
```
#### 场景 3：静态 IAM 令牌
```env
# IAM 令牌
TRACKER_IAM_TOKEN=您的_iam_令牌
# 组织 ID（选择一个）
TRACKER_CLOUD_ORG_ID=您的_cloud_org_id # 或 TRACKER_ORG_ID
```
#### 场景 4：使用服务帐户的动态 IAM 令牌
```env
# 服务帐户凭证
TRACKER_SA_KEY_ID=您的_key_id
TRACKER_SA_SERVICE_ACCOUNT_ID=您的_service_account_id
TRACKER_SA_PRIVATE_KEY=您的_private_key
# 组织 ID（选择一个）
TRACKER_CLOUD_ORG_ID=您的_cloud_org_id # 或 TRACKER_ORG_ID
```
#### 场景 5：OIDC 应用程序的联邦 OAuth（高级）
```env
# 启用带有 Yandex Cloud 联邦的 OAuth
OAUTH_ENABLED=true
OAUTH_SERVER_URL=https://auth.yandex.cloud/oauth
OAUTH_TOKEN_TYPE=Bearer
OAUTH_USE_SCOPES=false
OAUTH_CLIENT_ID=您的_oidc_client_id
OAUTH_CLIENT_SECRET=您的_oidc_client_secret
MCP_SERVER_PUBLIC_URL=https://您的-服务器.com
# 组织 ID（选择一个）
TRACKER_CLOUD_ORG_ID=您的_cloud_org_id # 或 TRACKER_ORG_ID
```
此配置启用通过 [Yandex Cloud OIDC 应用程序](https://yandex.cloud/ru/docs/organization/operations/applications/oidc-create) 的身份验证，这是 [Yandex Cloud 中的联合帐户](https://yandex.cloud/ru/docs/organization/operations/manage-federations) 所必需的。联合用户通过其组织的身份提供者（IdP）进行身份验证，并使用此 OAuth 流程访问 Yandex Tracker API。
### 重要注意事项
- 服务器按上述顺序检查身份验证方法
- 一次只能使用一种身份验证方法
- 对于生产环境，建议使用动态令牌（OAuth 或 IAM）以获得更好的安全性
- IAM 令牌的生命周期比 OAuth 令牌短，可能需要更频繁的更新
- 使用服务帐户时，请确保帐户具有 Yandex Tracker 的适当权限
## 配置
### 环境变量
```env
# 身份验证（使用以下方法之一）
# 方法 1：OAuth 令牌
TRACKER_TOKEN=您的_yandex_tracker_oauth_令牌
# 方法 2：IAM 令牌
TRACKER_IAM_TOKEN=您的_iam_令牌
# 方法 3：服务帐户（用于动态 IAM 令牌）
TRACKER_SA_KEY_ID=您的_key_id # 服务帐户密钥 ID
TRACKER_SA_SERVICE_ACCOUNT_ID=您的_sa_id # 服务帐户 ID
TRACKER_SA_PRIVATE_KEY=您的_private_key # 服务帐户私钥
# 组织配置（选择一个）
TRACKER_CLOUD_ORG_ID=您的_cloud_org_id # 用于 Yandex Cloud 组织
TRACKER_ORG_ID=您的_org_id # 用于 Yandex 360 组织
# API 配置（可选）
TRACKER_API_BASE_URL=https://api.tracker.yandex.net # 默认：https://api.tracker.yandex.net
TRACKER_HTTP_TIMEOUT=30 # 默认：30 秒每个请求（提高大附件的限制）
TRACKER_GET_RETRIES=2 # 默认：GET 请求的 2 次重试（适用于 429/502/503/504）
# 安全 - 限制对特定队列的访问（可选）
TRACKER_LIMIT_QUEUES=PROJ1,PROJ2,DEV # 用逗号分隔的队列密钥
# 问题-响应调整（可选）
TRACKER_HIDE_ISSUE_FIELDS=favorite,qaEngineer # 默认：favorite,qaEngineer。空字符串 = 保留所有内容。
# 远程 URL 附件上传（可选，默认禁用）
# 启用 `issue_attachments(action="upload", source_url="https://...")`
TRACKER_ATTACHMENT_URL_ALLOWED_DOMAINS=files.example.com,*.cdn.example.com # 启用时需要
TRACKER_ATTACHMENT_URL_MAX_BYTES=52428800 # 默认：50 MiB
TRACKER_ATTACHMENT_URL_TIMEOUT_SECONDS=30 # 默认：30 秒
# 服务器配置
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=您的_redis_密码 # 可选：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（适用于联邦，请使用 https://auth.yandex.cloud/oauth）
OAUTH_TOKEN_TYPE=<Bearer|OAuth|<empty>> # 默认：<empty>（需要为 Yandex Cloud 联邦设置为 Bearer）
OAUTH_USE_SCOPES=true # 默认：true（对于 Yandex Cloud 联邦，设置为 false）
OAUTH_CLIENT_ID=您的_oauth_client_id # 启用 OAuth 时需要
OAUTH_CLIENT_SECRET=您的_oauth_secret # 启用 OAuth 时需要
MCP_SERVER_PUBLIC_URL=https://您的.server.com # 启用 OAuth 时需要
TRACKER_READ_ONLY=true # 默认：false - 将 OAuth 限制为只读权限
```
## Docker 部署
### 使用预构建镜像（推荐）
```bash
# 使用环境文件
docker run --env-file .env -p 8000:8000 ghcr.io/aikts/yandex-tracker-mcp:latest
# 使用内联环境变量
docker run -e TRACKER_TOKEN=您的_token \
-e TRACKER_CLOUD_ORG_ID=您的_org_id \
-p 8000:8000 \
ghcr.io/aikts/yandex-tracker-mcp:latest
```
### 本地构建镜像
```bash
docker build -t yandex-tracker-mcp .
```
### Docker Compose
**使用预构建镜像：**
```yaml
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}
```
**本地构建：**
```yaml
version: '3.8'
services:
mcp-tracker:
build: .
ports:
- "8000:8000"
environment:
- TRACKER_TOKEN=${TRACKER_TOKEN}
- TRACKER_CLOUD_ORG_ID=${TRACKER_CLOUD_ORG_ID}
```
### 开发设置
```bash
# 克隆和设置
git clone https://github.com/aikts/yandex-tracker-mcp
cd yandex-tracker-mcp
# 安装开发依赖项
uv sync --dev
# 格式化和静态检查
task
```
## 许可证
该项目根据 [LICENSE](LICENSE) 文件中指定的条款获得许可。
## 支持
有关问题和疑问：
- 查看 Yandex Tracker API 文档
- 在 https://github.com/aikts/yandex-tracker-mcp/issues 上提交问题
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器