YouTrack (ymcp)

ymcp is a local toolchain for project work in YouTrack, including self-hosted instances behind a VPN. It has two parts: an MCP server for any AI client, and pipelines that hand issues to coding agents.

The MCP server speaks for you with your login and password, ships every tool of YouTrack’s built-in MCP server under the same names, and adds the ones it lacks: deleting things, sprints, attachments, history, time reports, commands and more.

• 58 tools: the 23 built-in ones, same names, arguments and limits, plus 35 extras
• Just a login and password: nothing to set up in YouTrack, no webhooks, OAuth client or API keys; the password lives in your system keychain
• Works without admin rights: field schemas, groups and comments fall back to what a regular user can read
• One-command install that registers itself in Claude, Cursor, VS Code, Zed, Codex, Gemini and 8 more clients
• Single static binary for macOS, Linux and Windows, with ymcp update built in

Pipelines take the issues a YouTrack search finds and give each one to a coding agent on its own branch.

• Claude Code, Kimi, opencode or any ACP agent, with the same YouTrack tools as the server
• Any Anthropic- or OpenAI-compatible model API for Claude Code: OpenRouter, Kimi for Coding, Z.ai, DeepSeek, MiniMax, Ollama or your own
• Branches, GitHub pull requests or GitLab merge requests, and the agent answers review comments
• Needs input when the agent has a question or wants a permission, with a system notification
• A TUI with a board per pipeline, or plain commands for scripts

Install

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

A given release instead of the latest, say to go back to it:

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

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/xlsft/ymcp/main/install.ps1))) -Version 0.22.0

Or with a package manager, then run ymcp setup:

brew install xlsft/tap/ymcp                                                  # macOS, Linux

scoop bucket add xlsft https://github.com/xlsft/scoop-bucket; scoop install ymcp # Windows

Package-managed copies update through their manager (brew upgrade ymcp and so on); ymcp update says so. Either way, ymcp update lists what each release since yours changed, and links the changelog.

The installer downloads the latest release and checks its SHA-256. It then runs ymcp setup, a TUI in the look of ymcp pipeline. With no profile yet it opens a new one, in three steps:

1. Connection: a profile name, youtrack by default, and your YouTrack URL, login and password, signed in to as you type; nothing is saved until they work;
2. Tools: the tools the profile serves, group by group or tool by tool, and whether destructive ones ask for your confirmation first (on by default, see Confirmations);
3. Clients: the MCP clients found on your machine, with a checkbox for each. Save registers ymcp as a stdio server in the ones you tick and removes it from the ones you untick.

Run ymcp setup again at any time to edit a profile, add or remove clients, or add another YouTrack.

An agent setting ymcp up for you (Cline and the like) has its own steps in llms-install.md.

Several YouTrack instances

Each YouTrack instance is a profile, and each profile is its own MCP server. The profile's display name gives the server name: YouTrack (work) becomes youtrack-work, youtrack-acme stays as it is. A repeated ymcp setup lists your profiles with their tools and clients: enter edits one (a rename moves its client entries along), n adds a profile and d removes one. Clients run ymcp --profile , so every instance shows up next to the others with its own tools.

Verify a release

Releases are signed keylessly with Sigstore by this repository's release workflow: checksums.txt has a checksums.txt.sigstore.json bundle, and each archive an 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

Each release also has SLSA build provenance for every file in checksums.txt, kept by GitHub and attached as ymcp.intoto.jsonl:

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

The Docker image is signed the same way and carries SBOM and provenance attestations:

cosign verify xlsoftware/ymcp:latest \

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

Commands

docs/reference.md has the full reference: every command, every tool and prompt with its inputs and outputs, and every field of the pipeline file.

Tools

Built-in YouTrack MCP set

Custom fields are set by their display name, e.g. {"State": "In Progress", "Fix versions": ["2.1"]}. ymcp looks up the field type and checks the value against the project before sending it. That includes the allowed assignees, so a wrong value comes back with the list of valid ones.

Extras

Every command takes --profile (or YMCP_PROFILE) to pick the YouTrack instance, e.g. ymcp --profile youtrack-acme check. Without it ymcp uses the youtrack profile, or the only one there is.

Tools that delete or bulk-change data are marked with destructiveHint, so clients ask before running them.

Errors tell the model what to do next. ymcp's own checks list what is allowed (value "X" is not allowed; allowed: Critical, Major, …), and errors from YouTrack get a hint by status: which tool finds the right ID after a 404, that a 403 needs a permission rather than a retry, that a 401 needs ymcp auth. HTML error pages from proxies are cut down to their title.

Prompts

Clients that support MCP prompts list these as slash commands. Each one tells the model which tools to use and in what order, and they never change YouTrack without asking:

A prompt is offered only when the tools it needs are served (see below).

Choosing tools

All 58 tools take room in the model's context. A profile can serve only some of them: pick groups or single tools in ymcp setup, or pass --tools (or YMCP_TOOLS) to serve, which wins over the profile.

| Group |