项目简介

YouTrack MCP Server 是一个基于 Model Context Protocol (MCP) 标准的后端服务，旨在通过一套标准化的工具和数据访问接口，使支持 MCP 的 AI 助手能够与 JetBrains YouTrack 问题追踪系统进行深度交互。它充当 AI 助手和 YouTrack API 之间的桥梁，使得 AI 能够理解并执行与 YouTrack 相关的任务。

主要功能点

问题管理:
- 获取指定问题的详细信息。
- 使用 YouTrack 查询语言搜索问题。
- 在指定项目中创建新问题。
- 为现有问题添加评论。
项目管理:
- 获取项目列表和特定项目详情。
- 创建和更新项目信息。
- 获取特定项目下的问题列表。
- 访问项目的自定义字段信息。
用户管理:
- 获取当前认证用户的信息。
- 按名称或登录名搜索用户。
- 获取用户详情及其所属群组。
高级搜索:
- 支持结合 YouTrack 查询语言进行高级搜索，包括排序选项。
- 提供结构化过滤（如按项目、经办人、状态、优先级等）。
- 支持按自定义字段的值进行搜索。

安装步骤

推荐使用 Docker 镜像进行安装和运行，这是最便捷的方式。

拉取 Docker 镜像：

docker pull tonyzorin/youtrack-mcp:latest

运行 Docker 容器： 运行容器时，你需要提供 YouTrack 实例的 URL 和 API Token 作为环境变量。'YOUTRACK_API_TOKEN' 是必需的，它通常是永久令牌，格式为 'perm:你的令牌值' 或 'perm-你的令牌值'。对于云版本，'YOUTRACK_URL' 可选，服务器会尝试从 Token 中解析；对于自托管版本，'YOUTRACK_URL' 是必需的。

对于 YouTrack Cloud 实例:

docker run -i --rm \
     -e YOUTRACK_URL=https://your-instance.youtrack.cloud \
     -e YOUTRACK_API_TOKEN=perm:your-api-token \
     tonyzorin/youtrack-mcp:latest

请将 'https://your-instance.youtrack.cloud' 替换为你实际的 YouTrack Cloud 地址，将 'perm:your-api-token' 替换为你实际的 API Token。

对于自托管 YouTrack 实例:

docker run -i --rm \
     -e YOUTRACK_URL=https://your-youtrack-server.com \
     -e YOUTRACK_API_TOKEN=perm:your-api-token \
     tonyzorin/youtrack-mcp:latest

请将 'https://your-youtrack-server.com' 替换为你实际的 YouTrack 服务器地址，将 'perm:your-api-token' 替换为你实际的 API Token。

'-i' 参数使容器的标准输入保持打开，以便在 'stdio' 模式下与 MCP 客户端通信。'--rm' 参数表示容器停止后自动删除。

服务器配置

MCP 服务器主要通过环境变量进行配置。这些环境变量在你运行 Docker 容器时通过 '-e' 参数传入。

'YOUTRACK_URL': 你的 YouTrack 实例的完整 URL (例如: 'https://your-instance.youtrack.cloud' 或 'https://your-server.com')。对于 YouTrack Cloud 实例，如果你使用永久令牌且令牌包含工作区信息（如 'perm:用户名.工作区...'），此变量可以省略。
'YOUTRACK_API_TOKEN': 连接 YouTrack API 所需的永久令牌。这是一个敏感信息，请妥善保管。例如: 'perm:your-token-string'。
'YOUTRACK_VERIFY_SSL': 是否验证 YouTrack 服务器的 SSL/TLS 证书。设置为 'false' 可以禁用验证，适用于自签名证书的自托管实例，但会降低安全性（默认: 'true'）。
'MCP_SERVER_NAME': 在 MCP 客户端中显示的服务器名称（默认: 'youtrack-mcp'）。
'MCP_SERVER_DESCRIPTION': 服务器的简短描述（默认: 'YouTrack MCP Server'）。
'MCP_DEBUG': 设置为 'true' 可以开启更详细的调试日志输出（默认: 'false'）。

MCP 客户端（如 Cursor, Claude Desktop, VS Code with Claude Extension）通常需要在一个 JSON 配置文件中配置 MCP 服务器的启动命令。例如，在 '.cursor/mcp.json' 或 '.vscode/mcp.json' 文件中添加一个条目。这个条目会指定 MCP 服务器的名称 ('name')、传输类型 ('type'，通常是 'stdio'）、用于启动服务器的命令 ('command') 及其参数 ('args')。'args' 参数列表应包含运行 Docker 容器的完整命令，包括所有必要的 '-e' 环境变量来传递你的 YouTrack 配置。

例如 (配置示例结构，请勿直接复制代码):

{
    "mcpServers": {
        "YouTrack": {
            "type": "stdio", // 或其他支持的传输类型
            "command": "docker", // 启动服务器的命令
            "args": [ // 传递给命令的参数列表
                "run", "-i", "--rm",
                "-e", "YOUTRACK_URL=...", 
                "-e", "YOUTRACK_API_TOKEN=...", 
                "tonyzorin/youtrack-mcp:latest"
            ]
        }
    }
}

注意: 具体的配置格式和位置取决于你使用的 MCP 客户端。请参考客户端的文档以获取详细说明。确保将 'YOUTRACK_URL' 和 'YOUTRACK_API_TOKEN' 参数值替换为你自己的 YouTrack 连接信息。

基本使用方法

一旦 MCP 服务器被配置并在你的 AI 助手中成功启动，你就可以通过自然语言指令来利用 YouTrack 的功能。AI 助手会识别你的意图，并通过 MCP 协议调用 YouTrack MCP 服务器提供的工具。

例如，你可以尝试以下指令：

获取问题详情：

Get details for issue DEMO-123

搜索问题：

Find all open issues assigned to me in the ProjectX project.

创建问题：

Create a new task in project MARKETING with the summary "Update website banner" and description "Design and implement a new banner for the homepage."

添加评论：

Add a comment to issue DOCS-45 saying "I've reviewed the document and it looks good."

AI 助手会将你的指令转换为对 YouTrack MCP 服务器工具的调用（例如 'get_issue', 'search_issues', 'create_issue', 'add_comment'），并将工具执行结果呈现给你。

关键词

项目简介

主要功能点

安装步骤

服务器配置

基本使用方法

信息