Yandex Tracker MCP

🚀 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

安裝步驟

1. 從 GitHub 發佈頁面 為你的操作系統和平臺下載 *.dxt 文件。
2. 雙擊下載的文件，將其安裝到 Claude Desktop 中。
3. 當提示時，提供你的 Yandex Tracker OAuth 令牌。
4. 確保擴展已啟用，現在你可以使用此 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。

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

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

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"

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

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

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

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

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

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

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

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

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

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

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

{
  "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 授權碼流程：

1. 客戶端註冊：你的 MCP 客戶端向服務器註冊以獲取客戶端憑證。
2. 授權：用戶被重定向到 Yandex OAuth 進行身份驗證。
3. 令牌交換：服務器將授權碼交換為訪問令牌。
4. API 訪問：客戶端使用承載令牌進行所有 API 請求。
5. 令牌刷新：過期的令牌可以在不重新進行身份驗證的情況下刷新。

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 應用

1. 訪問 Yandex OAuth 並創建一個新應用。
2. 將回調 URL 設置為：{MCP_SERVER_PUBLIC_URL}/oauth/yandex/callback。
3. 請求以下權限：
   • tracker:read - Tracker 的讀取權限。
   • tracker:write - Tracker 的寫入權限。
4. 保存你的客戶端 ID 和客戶端密鑰。

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 數據存儲後端（客戶端註冊、訪問令牌、刷新令牌和授權狀態）：

內存存儲（默認）

內存存儲將所有 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 支持多種身份驗證方法，並具有明確的優先級順序。服務器將根據以下層次結構使用第一個可用的身份驗證方法：

身份驗證優先級順序

1. 動態 OAuth 令牌（最高優先級）

• 當啟用 OAuth 且用戶通過 OAuth 流程進行身份驗證時。
• 令牌根據用戶會話動態獲取和刷新。
• 必需的環境變量：OAUTH_ENABLED=true、OAUTH_CLIENT_ID、OAUTH_CLIENT_SECRET、MCP_SERVER_PUBLIC_URL。

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（推薦用於交互式使用）

# 啟用 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 文檔。
• 在 此處 提交問題。