JetBrains Youtrack

YouTrack MCP

面向 JetBrains YouTrack 的开源 Model Context Protocol 服务。你可以在本地运行它（使用 Docker、npx 或 Python）。它通过 REST API 与 YouTrack Cloud 或 Server 通信，让 Cursor、Claude Desktop 和其他 MCP 客户端能够搜索、创建和更新问题。

此服务于 2025 年 4 月发布，比 JetBrains 在 YouTrack 2025.3（2025 年 10 月）中加入远程 MCP 早了约 6 个月。它不是官方服务的分支。

为什么它仍然存在

JetBrains 的官方 MCP 内置于 YouTrack 2025.3 及更高版本（Cloud 和 Server），地址为 https://<your-instance>/mcp。JetBrains 的新 MCP 功能（OAuth、时间跟踪、标签、草稿、自定义 YouTrack 应用）都在其中。如果你使用 2025.3 或更高版本，并希望采用厂商提供的方案，请使用它。

本项目是一个由你运行的进程。它调用 YouTrack REST API——也就是 /mcp 出现之前就已存在的同一 API。因此，它仍适用于尚未升级到 2025.3 的可自托管 Server。YouTrack 版本没有公布最低要求；只要你的实例能够签发永久令牌并提供 /api/issues，此服务就能与之通信。文章工具需要使用启用了知识库的 YouTrack。

	此 MCP	官方（2025.3 及更高版本）
历史	2025 年 4 月，早于官方版本	随 YouTrack 2025.3 发布（2025 年 10 月）
运行位置	你的设备（stdio / Docker）	YouTrack 内部（/mcp）
YouTrack 版本	REST API（包括 2025.3 之前的 Server）	2025.3 及更高版本
Cursor / Claude Desktop	原生 stdio	远程 HTTP，或 npx mcp-remote
字段更新	简单字符串：update_issue_state("DEMO-123", "In Progress")	获取字段架构，然后调用 update_issue
继续使用此方案的情况	较旧的 Server、本地 stdio、附件、项目管理、工具允许/拒绝列表	JetBrains 新 MCP 功能、OAuth、n8n/Zapier /mcp URL

快速开始

你需要一个 YouTrack URL 和一个永久 API 令牌。

Cursor / Claude Desktop（Docker）

{
  "mcpServers": {
    "youtrack": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "YOUTRACK_URL=https://your-instance.youtrack.cloud",
        "-e", "YOUTRACK_API_TOKEN=perm-xxx.your-token",
        "tonyzorin/youtrack-mcp:latest"
      ]
    }
  }
}

GHCR 上也提供相同镜像：ghcr.io/tonyzorin/youtrack-mcp:latest。

stdio 模式需要 -i（否则容器会立即退出）。Docker 无法读取 Cursor/Claude 的 env——请在 args 中使用 -e 传入 YouTrack 变量。若要限制工具，请再添加一行 -e，例如 ENABLED_TOOLS=get_issue,search_issues,create_issue,add_comment。

npx（无需 Docker）

{
  "mcpServers": {
    "youtrack": {
      "command": "npx",
      "args": ["-y", "youtrack-mcp-tonyzorin"],
      "env": {
        "YOUTRACK_URL": "https://your-instance.youtrack.cloud",
        "YOUTRACK_API_TOKEN": "perm-xxx.your-token"
      }
    }
  }
}

需要 Node.js 18+ 和 Python 3.14+。也通过 GitHub Packages 发布为 @tonyzorin/youtrack-mcp。

在终端中使用 Docker

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

latest 标签对应当前稳定版本（2.0.0）。若要固定镜像版本，请使用 tonyzorin/youtrack-mcp:2.0.0。WIP 和 PR 标签可用于测试；请勿在生产环境中使用。

Docker Compose（HTTP）

Compose 不会将客户端连接到 stdin，因此 stdio 会在启动后退出。请使用 streamable HTTP 并发布端口：

services:
  youtrack-mcp:
    image: tonyzorin/youtrack-mcp:latest
    ports:
      - "8000:8000"
    environment:
      YOUTRACK_URL: https://your-instance.youtrack.cloud
      YOUTRACK_API_TOKEN: perm-xxx.your-token
      TRANSPORT: streamable-http
      ENABLED_TOOLS: get_issue,search_issues,get_projects

将 Cursor / Claude Code 指向 http://localhost:8000/mcp。

从终端使用远程 HTTP：

docker run --rm -p 8000:8000 \
  -e YOUTRACK_URL="https://your-instance.youtrack.cloud" \
  -e YOUTRACK_API_TOKEN="perm-xxx.your-token" \
  tonyzorin/youtrack-mcp:latest \
  --transport streamable-http --host 0.0.0.0 --port 8000

可执行的操作

对于状态、优先级、经办人、类型和预估值，请传入简单字符串。嵌套的 { "name": "In Progress" } 对象会导致失败。

search_issues("project: DEMO #Unresolved")
get_issue("DEMO-123")
create_issue(project="DEMO", summary="Login fails on special characters", custom_fields={"Assignee": "admin", "Type": "Bug"})

update_issue_state("DEMO-123", "In Progress")
update_issue_priority("DEMO-123", "Critical")
update_issue_assignee("DEMO-123", "admin")
update_issue_type("DEMO-123", "Bug")
update_issue_estimation("DEMO-123", "4h")

add_comment("DEMO-123", "Reproduced on staging")
add_dependency("DEMO-123", "DEMO-124")

**工单：**搜索、获取、创建、更新、评论、关联（相关／依赖／重复）。

**自定义字段：**使用上方的专用辅助工具，以及 update_custom_fields、批量更新、架构和允许值查询。

**附件：**通过 get_issue_raw 列出，下载为 base64（get_attachment_content），删除。

**项目：**列出／获取、创建／更新、自定义字段架构、子系统、版本、构建。

**用户：**当前用户、查询、权限。

**文章：**获取、搜索、创建、更新、评论。

诊断：diagnose_workflow_restrictions、get_help。

配置

变量	必填	描述
YOUTRACK_URL	是	YouTrack 基础 URL（Cloud 或 Server）
YOUTRACK_API_TOKEN	是	永久令牌
YOUTRACK_VERIFY_SSL	否	SSL 验证，默认值为 true
DISABLED_TOOLS	否	要隐藏的工具，以逗号分隔（拒绝列表）
ENABLED_TOOLS	否	要保留的工具，以逗号分隔；隐藏其他所有工具（允许列表）

如果两者都设置，则允许列表优先。名称不区分大小写；连字符和下划线等效。

# Hide write tools
export DISABLED_TOOLS="create_issue,update_issue,delete_attachment"

# Read-only subset
export ENABLED_TOOLS="get_issue,search_issues,get_projects"

自签名 Server：YOUTRACK_VERIFY_SSL=false。

开发

• 测试
• CI：.github/workflows/ci.yml

支持

• GitHub Issues
• Telegram：t.me/tonyzorin

MIT。请参阅 LICENSE。