YouTrack (ymcp)

ymcp 是用于 YouTrack 项目工作的本地工具链，也支持通过 VPN 访问的可自托管实例。它包含两部分：供任意 AI 客户端使用的 MCP 服务，以及将问题交给编码 Agent 的流水线。

MCP服务使用你的登录名和密码代表你操作，提供 YouTrack 内置 MCP 服务的所有工具（名称保持一致），并补充其缺少的功能：删除内容、迭代、附件、历史记录、时间报告、命令等。

• 58 个工具：内置的 23 个工具（名称、参数和限制均相同），外加 35 个扩展工具
• 只需登录名和密码：无需在 YouTrack 中进行任何设置，也不需要 Webhook、OAuth 客户端或 API 密钥；密码存储在系统钥匙串中
• 无需管理员权限也能使用：字段架构、群组和评论会回退到普通用户可读取的内容
• 一条命令即可安装，并自动在 Claude、Cursor、VS Code、Zed、Codex、Gemini 和另外 8 个客户端中完成注册
• 单个静态二进制文件，适用于 macOS、Linux 和 Windows，并内置 ymcp update

流水线会获取 YouTrack 搜索结果中的问题，并将每个问题交给编码 Agent 在其独立分支上处理。

• Claude Code、Kimi、opencode 或任意 ACP Agent，均可使用与服务相同的 YouTrack 工具
• 分支、GitHub 拉取请求或 GitLab 合并请求，Agent 还会回复评审意见
• 需要输入时，如果 Agent 有疑问或需要权限，会发送系统通知
• TUI 为每条流水线提供一个看板，也可以使用普通命令编写脚本

安装

macOS / Linux：

curl -fsSL https://raw.githubusercontent.com/xlsft/ymcp/main/install.sh | sh

Windows（PowerShell）：

irm https://raw.githubusercontent.com/xlsft/ymcp/main/install.ps1 | iex

也可以使用包管理器安装，然后运行 ymcp setup：

brew install xlsft/tap/ymcp                                                  # macOS, Linux
scoop bucket add xlsft https://github.com/xlsft/scoop-bucket; scoop install ymcp   # Windows

通过包管理器安装的副本应通过对应的包管理器更新（例如 brew upgrade ymcp）；ymcp update 会提示这一点。

安装程序会下载最新发行版并校验其 SHA-256，然后运行 ymcp setup，该命令会：

1. 提示输入配置名称，默认为 youtrack；
2. 提示输入 YouTrack URL、登录名和密码，并在保存任何内容之前验证凭据；
3. 列出在你的计算机上找到的 MCP 客户端，并为每个客户端提供一个复选框；
4. 将 ymcp 注册为你选中的客户端中的 stdio 服务，并从取消选中的客户端中移除。

你可以随时再次运行 ymcp setup，以编辑配置、添加或移除客户端，或添加另一个 YouTrack 实例。

如果由 Agent（如 Cline）为你设置 ymcp，请参阅 llms-install.md 中的专属步骤。

多个 YouTrack 实例

每个 YouTrack 实例对应一个配置档，每个配置档都是独立的 MCP 服务。配置档的显示名称决定服务名称：YouTrack (work) 会变成 youtrack-work，youtrack-acme 则保持不变。再次运行 ymcp setup 会列出你的配置档：选择一个进行编辑、重命名（其客户端条目也会随之迁移），或添加、移除配置档。 客户端通过 ymcp --profile <key> 启动，因此每个实例都会与其他实例并列显示，并拥有各自的工具。

验证发行版本

本仓库的发行工作流使用 Sigstore 进行无密钥签名：checksums.txt 附有 checksums.txt.sigstore.json 捆绑文件，每个归档文件都附有 SPDX SBOM（*.sbom.json）。

cosign verify-blob checksums.txt --bundle checksums.txt.sigstore.json \
  --certificate-identity-regexp '^https://github.com/xlsft/ymcp/\.github/workflows/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com
sha256sum --ignore-missing -c checksums.txt

每个发行版本还为 checksums.txt 中的每个文件提供 SLSA 构建来源证明，由 GitHub 保管并以 ymcp.intoto.jsonl 附加：

gh attestation verify ymcp_linux_amd64.tar.gz --repo xlsft/ymcp

Docker 镜像也使用相同方式签名，并附带 SBOM 和来源证明证明：

cosign verify xlsoftware/ymcp:latest \
  --certificate-identity-regexp '^https://github.com/xlsft/ymcp/\.github/workflows/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

命令

docs/reference.md 提供完整参考：每条命令、每个工具和提示词及其输入与输出，以及流水线文件中的每个字段。

命令
ymcp / ymcp serve	通过 stdio 运行 MCP 服务（客户端启动的命令）。--transport http 会提供 Streamable HTTP 服务，参见 HTTP
ymcp setup	添加或编辑配置档、登录、选择其工具和 MCP 客户端。--name、--tools、--clients cursor,zed、--all、--reauth 和 --remove 可跳过交互提问
ymcp auth	设置或替换配置档的 URL、登录名和密码。脚本可使用 --url、--login、--proxy、--password-stdin
ymcp check	登录并显示你的身份
ymcp call <tool> '<json>'	调用一个工具，方式与客户端完全相同，例如 ymcp call count_issues '{"query":"#Unresolved"}'
ymcp health	检查运行中的 HTTP 服务是否响应（--url，默认为 http://127.0.0.1:8090）
ymcp logs	显示服务执行情况；-f 实时跟踪日志，-n 200 显示更多行
ymcp pipeline	打开流水线 TUI；ymcp pipeline --help 会列出 new、run、check、answer 等命令，参见 流水线
ymcp update	将二进制文件替换为最新发行版本（仅使用 --check 时只报告更新情况）
ymcp version	显示版本

工具

内置 YouTrack MCP 工具集

区域	工具
问题	search_issues、get_issue、create_issue、create_draft_issue、update_issue、change_issue_assignee、get_issue_fields_schema
评论、标签、链接、工时	add_issue_comment、get_issue_comments、manage_issue_tags、link_issues、log_work、get_saved_issue_searches
知识库	search_articles、get_article、create_article、update_article
项目和人员	find_projects、get_project、find_user、get_current_user、find_user_groups、get_user_group_members

自定义字段通过其显示名称设置，例如 {"State": "In Progress", "Fix versions": ["2.1"]}。ymcp 会查询字段类型，并在发送前根据项目检查值。这也包括允许的受派人，因此如果值无效，返回结果会列出有效选项。

额外功能

领域	工具
删除和撤销	delete_issue、delete_issue_comment、restore_issue_comment、delete_article、delete_work_item、unlink_issues
敏捷看板和迭代	find_agile_boards、get_agile_board、get_sprint、create_sprint、update_sprint、add_issue_to_sprint、remove_issue_from_sprint、delete_sprint
历史记录和报告	get_issue_activities、count_issues、get_time_report、get_issue_work_items
批量修改	apply_command：对问题或查询（最多 100 项）执行 YouTrack 命令对话框中的任意命令；执行前会先验证，并支持 dryRun
附件	问题和知识库文章的附件：get_issue_attachments、get_attachment（文本以内联形式显示，图片以图片形式显示，其他文件保存到本地）、add_attachment（一次添加多个文件）、delete_attachment
评论	update_issue_comment
局部文本编辑	edit_issue_description、edit_article_content：在描述或文章中查找并替换，可精确匹配，也可使用带捕获组的正则表达式，因此小幅修改无需重新发送全文
VCS	get_issue_vcs_changes：来自 GitHub、GitLab、Bitbucket、Gitea 或 TeamCity 集成的提交和拉取请求
标签和已保存的搜索	find_tags、create_tag、update_tag、delete_tag、create_saved_search、update_saved_search、delete_saved_search
备用入口	call_api：以你的身份调用任意 YouTrack 或 Hub REST 端点，供其他工具无法覆盖的场景使用

每条命令都接受 --profile <key>（或 YMCP_PROFILE），用于选择 YouTrack 实例，例如： ymcp --profile youtrack-acme check。如果未指定，ymcp 会使用 youtrack 配置；如果只有一个配置，则使用该配置。

删除或批量修改数据的工具带有 destructiveHint 标记，因此客户端会在运行前询问。

错误信息会告诉模型接下来该怎么做。ymcp 自带的检查会列出允许的值（value "X" is not allowed; allowed: Critical, Major, …）；YouTrack 返回的错误会根据状态码给出提示：404 时应使用哪个工具查找正确的 ID；403 表示需要相应权限，而不是重试；401 表示需要运行 ymcp auth。代理返回的 HTML 错误页面会精简到只保留标题。

提示词

支持 MCP 提示词的客户端会将这些提示词列为斜杠命令。每个提示词都会告诉模型要使用哪些工具以及使用顺序，而且绝不会在未询问的情况下更改 YouTrack：

提示词
standup	自上一个工作日以来我做了什么（如果今天是星期一，则从星期五算起）、接下来要做什么、有哪些阻碍。days 可查看更多天数
triage	某个 project 中尚未分类的问题，并提供类型、优先级、负责人和重复项建议；只会应用你批准的内容
sprint_report	某个 board 的迭代报告：已完成和未完成的工作、每个人负责的事项、范围变更、记录的工时和风险
issue_brief	了解某个 issue 的情况：概要、状态、决策、未解决的问题和后续步骤

只有在所需工具已提供时，才会提供提示词（见下文）。

选择工具

全部 58 个工具都会占用模型上下文。配置可以只提供其中的某些工具组：在 ymcp setup 中选择，或在 serve 中传入 --tools（或 YMCP_TOOLS）；后者优先于配置中的设置。

组	工具
issues	搜索、计数、读取、创建、编辑、草稿、删除、命令、关联、历史记录、VCS 变更
comments	读取、添加、编辑、删除、恢复
attachments	问题和文章中的文件
articles	知识库
time	工作项和工时报告
agile	看板和迭代
projects	查找和描述项目
people	用户和用户组
tags	标签和问题标记
searches	已保存的搜索
api	call_api

选择项可以混合使用工具组和工具名称，- 用于移除某项：issues,comments,articles,-delete_issue。如果只列出要移除的项，则会从全部工具开始，例如 -api,-agile。启动日志会显示已提供的工具，例如： tools="19 of 58: issues, comments, -delete_issue"。

工作流

工作流会监控 YouTrack 搜索，并将找到的每个议题交给编码 Agent。Agent 会在自己的 git 工作树中新建分支并开展工作。ymcp 会推送该分支、创建拉取请求或合并请求，并持续将审查评论交给 Agent，直到变更合并。工作流需要本地安装：它们不包含在 Docker 镜像中。Agent 会在本机或 SSH 主机（workspace.host，即 ~/.ssh/config 中的别名）上工作。

站点工作流 会在 main 每次变更时，根据 TUI 自身的代码绘制这些内容。

运行 ymcp pipeline 打开 TUI：查看你的配置、以卡片形式展示的工作流、每个工作流的看板，以及等待你处理的运行收件箱。按 n 使用向导创建工作流。在看板卡片、运行或仍在待办列表中的议题上按 enter，即可像查看 YouTrack 议题一样打开它：查看描述和评论、拉取请求讨论串（[ 和 ]）以及 Agent 日志；评论框（enter）支持通过 / 补全下方命令；按 r 重新加载看板或卡片。按 t 可在卡片上方打开运行记录：查看 Agent 的思考和发言、它运行的每个工具及其查看的文件、命令或模式，以及收到的回复，内容会实时更新。议题中所有有值的字段都会显示在卡片顶部，每行四个，放在标题旁边；放不下时则显示在标题下方。按 e 可列出项目字段并进行更改：选择一个值、添加或移除多个值之一，或输入数字。更改后，如果待办议题不再符合来源查询条件，它就会从看板中移除。快捷键也适用于西里尔字母键盘布局。在 kitty 和 Ghostty 中，卡片会直接显示图片，包括粘贴的屏幕截图和附件，并会播放 Agent 的工作加载动画；其他终端和 tmux 则会显示图片链接。可使用 YMCP_IMAGES=kitty 或 YMCP_IMAGES=off 覆盖选择。也可以从命令行运行：

ymcp pipeline new backend --profile youtrack --dir ~/src/backend --query 'project: BE #Unresolved tag: ai'
ymcp pipeline backend edit     # adjust the stage commands to your workflow
ymcp pipeline backend check    # profile, query, stages, git and agent
ymcp pipeline backend run -d   # run in the background; `stop` stops it

ymcp pipeline --help 会列出所有命令，包括 status、runs、logs、answer、cancel 和 delete。每个工作流都是 <config dir>/ymcp/pipelines/ 中的一个 JSON 文件，运行记录保存在 <config dir>/ymcp/state.db 中。

阶段

源查询使用与已保存搜索相同的语法。它找到的每个 issue 都会沿着流水线的看板流转：

阶段
Backlog	源查询找到且尚未运行的 issue
Working	Agent 处理 issue。ymcp 会应用此阶段的 YouTrack 命令，默认为 State In Progress
Needs input	Agent 提出了问题、需要权限、超时或失败。ymcp 会在评论中说明原因，并应用 tag needs-input
Review	Agent 已完成工作并推送了分支。默认命令为 State Fixed
Done	默认关闭。当变更合并或 issue 符合此阶段的查询时进入此阶段
Closed	变更未合并便已关闭，或 issue 符合此阶段的查询。回复 /cancel 时也会运行其可选命令

每个阶段都有一个 enter 命令（按 YouTrack 命令对话框中的格式填写）以及一个用于识别该阶段 issue 的 match 查询。Working 命令应将 issue 移出源查询：将其移回源查询会取消运行。取消运行（也可使用 ymcp pipeline NAME cancel N）会添加评论并关闭其拉取请求或合并请求，保留分支；除非设置了 workspace.keepWorktree，否则会移除其工作树；之后再次运行该 issue 时会从新分支开始。移回 Backlog 以取消运行的 issue，在离开源查询之前不会再次被选取；其他方式取消的 issue 则会在重新符合源查询条件后再次被选取。未合并便关闭的变更会使运行以 Closed 状态结束。workspace.parallel 设置可同时运行的 issue 数量（1）。

已结束的运行可以通过看板或运行卡片上的 d 删除，也可以使用 ymcp pipeline NAME delete N 删除：其日志会被删除，但 issue、分支和变更会保留；Backlog 中的 issue 会再次被选取。取消的运行只有在 runner 关闭其变更并移除其工作树后才能删除。

Agent 提交时使用仓库的 user.name 和 user.email。启用 workspace.identity.enabled 后，每个工作树中都会为 Agent 设置独立的作者身份，且只写入该工作树的配置。workspace.identity.name 是名称模板（{{agent.name}} · {{pipeline.name}} #{{run.number}}），workspace.identity.tag 是地址中 + 后面的内容模板（agent_{{pipeline.name}}_{{run.number}}，因此 [email protected] 会变成 [email protected]）。两者也可以使用 issue 的键；标签仅保留小写字母、数字和 _。

每条提交消息都以 workspace.commitPrefix（{{issue.id}}）开头。若无需前缀，可将其设为 ""，例如仓库使用 commitlint 时：Agent 随后会按照仓库的规范编写提交消息。strategy.title 是 PR/MR 标题模板（{{issue.key}} {{issue.summary}}）；{{commit.subject}} 是分支上首条提交的主题，因此设置 "title": "{{commit.subject}}" 即可生成符合规范的标题，且压缩合并会保留该标题。

Agent

agent.provider
claude	通过 CLI 使用 Claude Code，采用 stream-json 的 claude -p，每轮启动一个进程，并在轮次间使用 --resume
kimi	通过 ACP 使用 Kimi Code，命令为 kimi acp
opencode	通过 ACP 使用 opencode，命令为 opencode acp
acp	任何其他支持 ACP 的 Agent，由 agent.command 启动

每次运行都会在回环端口上启动一个专属 MCP 服务，并为其分配专属令牌；Agent 通过它获取 YouTrack 工具，作为流水线的配置文件。密码和 YouTrack 令牌都保存在 ymcp 中，不会离开你的设备。另有两个工具可访问运行器：request_input 会向你提问，report 会发布简短状态。

Agent 可以执行哪些操作，取决于它自身的设置：运行模式（agent.mode，例如 Claude 的 acceptEdits）和参数（agent.args，例如 --allowedTools）。当 Agent 请求使用它可能无权使用的工具时，由流水线的 permissions 决定如何处理：ask（默认值）会将运行状态设为需要输入，allow 会批准所有请求，deny 会拒绝所有请求，Agent 则会在不使用该工具的情况下继续运行。新建的 Claude 流水线会在 agent.args 中默认加入 --dangerously-skip-permissions，因此 Claude 无需询问即可使用所有工具；若要限制它，请改用运行模式或 --allowedTools。新建的 Kimi 流水线会以 Kimi 的 yolo 模式启动，原因相同；auto 只会批准 Kimi 认为安全的操作，而 default 会对所有操作进行询问。

每轮开始前，ymcp 都会获取 origin，因此 Agent 可以变基到基础分支，而无需自行获取。

策略

strategy.kind
branch	仅推送分支（默认值）。反馈仅来自 YouTrack
github-pr	拉取请求
github-issue-pr	一个镜像 YouTrack 工单的 GitHub issue，以及一个用于关闭该 issue 的拉取请求
gitlab-mr	在 gitlab.com 或可自托管的 GitLab 上创建合并请求，并根据 origin URL 查找目标

推送后，Agent 会在自己单独的一轮中撰写 PR/MR 标题和说明：ymcp 会使用 prompts.describe 恢复其会话，并将其传递给 set_change 工具的内容写入 PR/MR，因此 Agent 工作期间说的内容不会出现在其中。请在 prompts.describe 中设置相关规则（语言、格式、链接）。如果 Agent 没有调用该工具，系统会再询问一次，然后将它对这一轮的回答作为说明。之后的推送会以相同方式更新 PR/MR，除非有人在托管平台上编辑过它。"strategy": {"describe": false} 会根据 strategy.title 和该轮的回答创建 PR/MR。strategy.draft 会将它们创建为草稿。对于 gitlab-mr，strategy.squash 和 strategy.deleteBranch 会勾选合并请求中的“Squash commits”和“Delete source branch”选项。令牌取自 gh 或 glab（取决于你登录该托管平台时使用的工具），也可以从系统钥匙串中获取（服务 ymcp，账户 vcs:<host>）。

CI

每次推送后，运行器都会监视所推送提交的 CI：GitHub 的检查运行和提交状态，或 GitLab 流水线。所有策略都支持此功能；branch 会读取 origin 所指向托管平台上的 CI，并使用相同的令牌。如果运行处于审查阶段时 CI 失败，Agent 会收到一轮，内容包括失败的作业及其日志末尾部分，并将回答发送到工单。连续进行 ci.fixes 次（3 次）这样的轮次后，下一次失败会将运行状态设为需要输入；由人工发起的轮次会重新开始计数。卡片日志会显示 CI 的运行、通过和失败状态。"ci": {"watch": false} 可关闭此功能。

Agent 消息

Agent 在 YouTrack 或拉取请求中撰写的所有内容，都会以隐藏标记和标题开头：

@xlsft's agent #17 (backend)

Done: branch BE-123-fix-login, PR https://github.com/acme/api/pull/42

该标记是 HTML 注释，因此 YouTrack、GitHub 和 GitLab 不会显示它；ymcp 用它来区分 Agent 的消息和你的消息。标题会注明 Agent 名称、运行编号和流水线。Agent 开始处理消息时，ymcp 会立即以动画 ymcp 徽标进行回复，之后再将该评论编辑为回答，或编辑为运行停止的原因。

反馈和需要输入

Agent 会响应你的评论：来自个人资料中 YouTrack 账户以及 gh 或 glab 账户的评论。将其他登录账户添加到 feedback.youtrack、feedback.github 和 feedback.gitlab；其他人的评论会被跳过。在 feedback.debounce（60s）时间内收到的评论会一并发送给 Agent。

当 Agent 提出问题、请求权限、静默达到 timeouts.silence（10m）、运行时间超过 timeouts.total（2h）或运行失败时，运行会等待输入。允许的作者发来的第一条回复会让运行继续：可以是在 YouTrack 中的评论、拉取请求上的评论、TUI 收件箱中的回复，或 ymcp pipeline backend answer 17 "…"。权限请求需要回复 /approve 或 /reject；如果在 timeouts.permission（30m）内没有回复，请求将被拒绝。 对于 Claude，/approve 只会在本次运行的剩余时间内，允许此前被拒绝的调用（Bash(<command>)、Edit(//<path>) 等），而不会放行整个工具；复合命令会为其中每条命令分别添加规则；无法写成这类规则的调用（例如通配符、子 shell）仍会被拒绝。

另外三种回复由 ymcp 自行处理，Agent 不会看到：

回复
/clear	隐藏本次运行在 YouTrack 和拉取或合并请求中的所有评论，包括你和 Agent 的评论。评论仍保留在历史记录中：YouTrack 会将其标记为已删除，并允许恢复；GitHub 会将其折叠为过时内容；GitLab 会解决相应的讨论串（讨论串外的普通评论仍会显示）
/compact	让 Agent 使用工作流的 language 总结本次运行，然后清除运行内容，只留下总结以及指向更改和分支的链接，作为唯一评论
/cancel [why]	像执行 ymcp pipeline NAME cancel N 一样取消运行，并使用已关闭阶段的命令关闭 issue

"autoCompact": true 会压缩每个以完成或关闭状态结束的运行。命令只会执行一次：恢复其评论不会再次执行该命令。

通知

默认情况下，当运行需要输入或失败时，ymcp 会显示带有其图标的系统通知。点击通知会打开问题、拉取请求或 issue。此功能支持 macOS、Windows 和 Linux（Linux 需要 D-Bus 通知守护进程）。

ymcp pipeline notify                                   # what is on and whether it works here
ymcp pipeline notify test                              # send a test notification
ymcp pipeline notify set toast.events=needs_input,run_failed,review_ready

事件包括 needs_input、run_failed、review_ready、run_done 和 runner_stopped。工作流可以通过在其 JSON 中设置 "notifications": {"events": [...]} 来筛选事件。

提示词预设

Agent 的提示词来自某个预设：fix（默认）、bugfix-test-first、feature、refactor、docs 或 investigate。运行 ymcp pipeline presets 可查看每个预设的用途。prompts.start、prompts.feedback 和 prompts.answer 会替换预设中的文本，并支持 {{issue.id}} 和 {{branch}} 等占位符。 language（默认为 English）是 Agent 在公开场合撰写内容所用的语言，包括评论、拉取请求和提交消息。

内置预设为只读；你自己的预设存放在配置文件旁的 presets/ 目录中。 ymcp pipeline presets copy fix mine 会创建一个预设，可通过 presets edit mine 修改；presets save NAME --from PIPELINE 会保存你在工作流中调整过的提示词。rename 和 rm 会执行其名称所示的操作。 工作流会复制预设中的文本，因此修改或删除预设不会改变工作流。

配置

ymcp setup 和 ymcp auth 会将每个配置文件的名称、URL、登录信息和代理设置存储在 <config dir>/ymcp/config.json 中， 该文件仅你本人可读：

• macOS：~/Library/Application Support
• Linux：~/.config
• Windows：%APPDATA%

密码会存储在系统密钥链中：macOS 上为 Keychain，Linux 上为 Secret Service，Windows 上为 Credential Manager。 仅在没有密钥链的情况下，密码才会回退到配置文件中。

环境变量会覆盖当前使用的配置文件中存储的值。这在 CI 中很实用：

变量
YOUTRACK_URL	实例根 URL，例如 https://youtrack.example.com（不含 /api）
YOUTRACK_LOGIN、YOUTRACK_PASSWORD	YouTrack 或 Hub 账户，包括 LDAP 账户
YOUTRACK_PROXY	留空则使用 HTTP(S)_PROXY（如果该代理无法连接 YouTrack，则直接连接）；设为 none 则始终直接连接；也可以填写代理 URL
YMCP_PROFILE	要使用的配置文件，例如 --profile
YMCP_TOOLS	要提供的工具，例如 serve --tools
YMCP_CONFIG	配置文件的路径

--env FILE 会从 dotenv 文件加载这些变量（参见 .env.example）。

在 VPN 后面？ MCP 客户端通常会传入用于访问互联网的 HTTP(S)_PROXY。此类代理会通过公共 DNS 解析内部 YouTrack，因此永远无法连接到它。如果代理来自环境变量且无法连接 YouTrack，ymcp 会改为直接连接，并记录原因。显式配置的代理始终会被使用。

HTTP

ymcp serve --transport http 会通过 Streamable HTTP 在一个进程中提供所有配置文件，每个配置文件使用各自的路径：

YMCP_HTTP_TOKEN=$(openssl rand -hex 32) ymcp serve --transport http --addr 127.0.0.1:8090

启动日志会列出每个配置文件及其 URL，例如 http://127.0.0.1:8090/youtrack-acme。默认配置文件也会在 / 提供。--profiles a,b 只提供指定的配置文件，--profile a 则只提供一个。无法登录的配置文件会被跳过，并显示警告。

GET /healthz 无需令牌即可返回 {"status":"ok","version":"…"}，供负载均衡器和监控使用；ymcp health 可从命令行检查该接口。Docker 镜像会将其用作 HEALTHCHECK。

使用 --token 或 YMCP_HTTP_TOKEN 时，每个请求都必须携带 Authorization: Bearer <token>；请在客户端针对该 URL 的条目中设置此请求头。如果未设置令牌，任何能够访问服务器的人都可以使用它，因此请将服务器绑定到 127.0.0.1（默认值）或设置令牌；如果服务器在其他地址监听且未设置令牌，ymcp 会发出警告。

Docker

xlsoftware/ymcp 镜像会运行 HTTP 服务，支持 linux/amd64 和 linux/arm64。 配置文件存放在 /config 卷中。容器中没有密钥链，因此密码会保存在该卷的配置文件中（权限模式为 0600）；请将该卷视为机密数据。镜像仅包含 MCP 服务；流水线 需要本地安装。

添加配置文件。auth 会提示输入 URL、登录信息和密码，并在保存前验证这些信息：

docker run -it --rm -v ymcp:/config xlsoftware/ymcp auth
docker run -it --rm -v ymcp:/config xlsoftware/ymcp --profile youtrack-acme auth   # another instance

使用令牌在端口 8090 上运行服务：

docker run -d --name ymcp --restart unless-stopped \
  -p 127.0.0.1:8090:8090 -v ymcp:/config \
  -e YMCP_HTTP_TOKEN="$(openssl rand -hex 32)" \
  xlsoftware/ymcp
docker logs ymcp   # lists each profile and its URL

如果只运行单个实例且不使用卷，也可以直接传入连接信息： -e YOUTRACK_URL=https://youtrack.example.com -e YOUTRACK_LOGIN=… -e YOUTRACK_PASSWORD=…。

然后让客户端使用带令牌的配置文件 URL，例如在 Claude Code 中：

claude mcp add --transport http youtrack http://127.0.0.1:8090/youtrack --header "Authorization: Bearer <token>"

或在 JSON 配置中：

{ "mcpServers": { "youtrack": { "type": "http", "url": "http://127.0.0.1:8090/youtrack",
  "headers": { "Authorization": "Bearer <token>" } } } }

该镜像也支持 stdio，每个客户端运行一个实例；这也是 MCP Registry 将其列为 io.github.xlsft/ymcp 的运行方式。通过注册表安装的客户端可运行：

docker run -i --rm -e YOUTRACK_URL -e YOUTRACK_LOGIN -e YOUTRACK_PASSWORD xlsoftware/ymcp serve

重试

YouTrack 繁忙或正在重启时，工具调用不会立即失败。ymcp 最多重试三次，等待 0.5、1 和 2 秒；如果 Retry-After 要求等待更久，则按其要求等待（最多 10 s）：任何请求遇到 429 和 503 时都会重试；只有可安全重复的请求遇到 502、504 和连接中断时才会重试。可能已经创建问题或评论的 POST 请求绝不会发送两次。每次重试都会记录日志。

日志

服务会记录启动信息、每个连接的客户端以及每次工具调用。启动时还会在后台检查 GitHub；如果有更新版本，会记录 update available current=0.4.0 latest=0.5.0 run="ymcp update"。每行都包含参数、调用耗时以及任何错误。登录也会记录。日志会写入 stderr，Claude Desktop 等客户端会将其保存在各自的 MCP 日志中。日志也会追加到文件中，因此客户端运行 ymcp 时，你可以查看日志：

ymcp logs -f

在 macOS 上，日志文件位于 ~/Library/Logs/ymcp/ymcp.log；在 Linux 上，位于 ~/.local/state/ymcp/ymcp.log；在 Windows 上，位于 %LOCALAPPDATA%\ymcp\logs\ymcp.log。文件达到 5 MB 时会轮换。

设置
ymcp -v serve 或 YMCP_LOG_LEVEL=debug	还会记录每个 YouTrack 和 Hub 请求的状态与耗时
YMCP_LOG_LEVEL	debug、info（默认）、warn 或 error
YMCP_LOG_FILE	指定其他日志文件路径，或设为 off
YMCP_UPDATE_CHECK=off	启动时不检查是否有更新版本

若要在客户端启用 debug 级别的日志记录，请在其 ymcp 条目中添加 "env": {"YMCP_LOG_LEVEL": "debug"}。

支持的客户端

Claude Code · Claude Desktop · Cursor · VS Code（Copilot）· Windsurf · Devin Desktop · Zed · Codex · Gemini CLI · Antigravity · JetBrains Junie · Cline · LM Studio · opencode · Kimi Code

Claude Desktop 运行时会根据内存中的配置覆盖配置文件，因此期间所做的修改会丢失。所以，ymcp setup 会询问是否在修改期间退出 Claude Desktop，并在修改后重新打开它。

ymcp 会直接修改各客户端的配置，并保留其他服务、密钥和注释。它会在原文件旁保留一份 .ymcp.bak 副本。对于其他客户端，请为每个配置文件注册一个标准输入/输出服务，让它运行带有 --profile <key> 的 ymcp 二进制文件：

{ "mcpServers": { "youtrack": { "command": "/path/to/ymcp", "args": ["--profile", "youtrack"] } } }

登录方式

YouTrack 的 OAuth 密码授权需要服务密钥，而普通用户没有服务密钥。因此，ymcp 会使用登录名和密码通过 Hub 登录：

1. 从公开的 /api/config 读取 Hub 地址和 YouTrack 服务 ID。
2. 提交 Hub 登录表单并保留会话 Cookie。
3. 执行 YouTrack Web 客户端的隐式 OAuth 流程，并从重定向中获取 bearer token。

过期的 token 会通过会话续期，不会重新发送密码。只有会话本身过期时，才会再次发送密码。Hub API 需要使用单独的 Hub 范围 token；该 token 会在需要时获取。暂不支持双因素身份验证。

开发

go build -o bin/ymcp ./cmd/ymcp
go test -race ./...
./bin/ymcp --env .env call get_current_user

单元测试不会访问网络。internal/youtrack/youtracktest 会模拟 YouTrack 和 Hub，包括登录表单、OAuth 重定向和 token 撤销。工具测试通过内存中的 MCP 客户端调用工具，并检查它们发送的 REST 请求。

端到端测试（e2e/）会通过标准输入/输出运行构建好的二进制文件，并连接到真实的 YouTrack。它们会在临时项目上调用全部 58 个工具，并删除创建的所有内容。每次推送时，CI 都会运行这些测试；此外还会每晚运行一次。

提交和发布流程请参阅 CONTRIBUTING.md。

许可证

MIT。与 JetBrains 无关联；YouTrack 是 JetBrains s.r.o. 的商标。