YouTrack (ymcp)

[ymcp — It’s fun to fetch with the 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, Linuxscoop 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 <key>, 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.comsha256sum --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 <key> (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.

A selection mixes groups and tool names, and - removes one: issues,comments,articles,-delete_issue. Removals alone start from everything, e.g. -api,-agile. The start-up log shows what is served, e.g. tools="19 of 58: issues, comments, -delete_issue".

Confirmations

Destructive tools ask for your confirmation before they change anything: the deletes, unlink_issues, apply_command with a command that removes something, and call_api with DELETE. Called the first time, such a tool does nothing and returns an operation id and a one-time secret, with a note for the model to ask you. If you agree, the model calls it again with the same arguments and confirm set to the secret. A secret works once, for those arguments, for 10 minutes.

It is on by default. Turn it off for a profile in ymcp setup (or ymcp setup --confirm off --all), or for one server with serve --confirm off (or YMCP_CONFIRM=off), and the tools run at once, as they used to. ymcp call and pipeline agents never ask: a person runs the former, and nobody waits on the latter.

Pipelines

A pipeline watches a YouTrack search and gives each issue it finds to a coding agent. The agent works in its own git worktree on a new branch. ymcp pushes the branch, opens a pull or merge request and brings the agent the review comments until the change is merged. Pipelines need a local install: they are not in the Docker image. The agent works on this machine or on an SSH host (workspace.host, an alias from ~/.ssh/config).

[A pipeline's board: backlog, working, needs input, review and done] [A run card: the issue, its comments and the agent's question] [The agent asks for a permission; /approve or /reject answers] [Changing the issue's fields from the card]

The Site workflow draws these from the TUI's own code on every change to main.

Run ymcp pipeline to open the TUI: your profiles, their pipelines as cards, a board per pipeline and an inbox of runs that wait for you. Press n to create a pipeline with the wizard. x exports the pipeline under the cursor to a file, X every pipeline of the profile, and I imports a file into the profile; the system's file dialog picks the file (over SSH you type the path). The file carries your own presets that the pipelines use; a name that is taken gets a number, as backend-2. enter on a card of the board, a run or an issue still in the backlog, opens it like a YouTrack issue: the description and comments, the pull request thread ([ and ]) and the agent's log, with a comment box (enter) whose / completes the commands below; r reloads the board or the card. t opens the run's transcript over the card: what the agent thinks and says, every tool it runs with the file, command or pattern it looks at, and the replies it gets, followed live. Every field of the issue that has a value shows at the top of the card, four to a row, beside the title or under it when it doesn't fit. e lists the project's fields to change one: pick a value, add or remove one of several, or type a number. A backlog issue the source query no longer finds after the change leaves the board. Shortcuts work on Cyrillic keyboard layouts too. In kitty and Ghostty the card shows pictures in place, pasted screenshots and attachments included, and the agent's working loader plays; other terminals, and tmux, get links to them. YMCP_IMAGES=kitty or YMCP_IMAGES=off overrides the choice. Or from the command line:

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 workflowymcp pipeline backend check    # profile, query, stages, git and agentymcp pipeline backend run -d   # run in the background; `stop` stops it

ymcp pipeline --help lists every command, including status, runs, logs, answer, cancel and delete. Each pipeline is a JSON file in <config dir>/ymcp/pipelines/, and runs are kept in <config dir>/ymcp/state.db.

Stages

The source query uses the same syntax as a saved search. Each issue it finds moves along the pipeline's board:

Each stage has an enter command, as typed in YouTrack's command dialog, and a match query that recognizes issues in it. The working command should take the issue out of the source query: moving it back there cancels the run. A canceled run (also ymcp pipeline NAME cancel N) closes its pull or merge request with a comment, keeps its branch and removes its worktree unless workspace.keepWorktree is set; a later run of the issue starts on a new branch. An issue moved back to the backlog to cancel its run is not taken again until it leaves the source; one canceled otherwise is taken again once it is back in the source. A change closed without a merge ends the run as closed. workspace.parallel sets how many issues run at once (1).

A run that ended as done reopens when its issue, having left the working, review and needs-input stages, is moved back into one of them within 30 days, say from done to review because it needs more work. The run goes back to review with the agent's session and branch; the comments written on the issue since it ended are its feedback, and if its change was merged or closed, the next push opens a new one. An issue still in review when its change was merged has not left, so it doesn't reopen the run.

A run that has ended can be deleted from the local store with d on the board or the run's card, or with ymcp pipeline NAME delete N: its log goes, the issue, branch and change stay, and an issue the backlog held is taken again. A canceled run can be deleted once a runner has closed its change and removed its worktree.

The agent commits as the repository's user.name and user.email. With workspace.identity.enabled it gets an author of its own in each worktree instead, written to the worktree's config only. workspace.identity.name is a template of the name ({{agent.name}} · {{pipeline.name}} #{{run.number}}) and workspace.identity.tag of what goes after + in your address (agent_{{pipeline.name}}_{{run.number}}, so [email protected] becomes [email protected]). Both take the issue's keys too; the tag keeps lowercase letters, digits and _.

Every commit message starts with workspace.commitPrefix ({{issue.id}}). Set it to "" for none, e.g. when the repository runs commitlint: the agent then writes its commit messages the repository's way. strategy.title is the template of the PR/MR title ({{issue.key}} {{issue.summary}}); {{commit.subject}} is the subject of the branch's first commit, so "title": "{{commit.subject}}" gives a conventional title, which a squash merge keeps.

Agents

Each run gets its own MCP server on a loopback port with its own token, and the agent gets the YouTrack tools through it, as the pipeline's profile. The password and the YouTrack token stay in ymcp and never leave your machine. Two more tools reach the runner: request_input asks you a question, report posts a short status.

What the agent may do is up to the agent's own settings: its mode (agent.mode, e.g. Claude's acceptEdits) and its arguments (agent.args, e.g. --allowedTools). When it asks for a tool it may not use, the pipeline's permissions decides: ask (default) puts the run in needs input, allow approves every request, deny refuses every one and the agent goes on without the tool. New Claude pipelines start with --dangerously-skip-permissions in agent.args, so Claude runs every tool without asking; replace it with a mode or --allowedTools to restrict it. New Kimi pipelines start in Kimi's yolo mode for the same reason; auto approves only what Kimi deems safe and default asks about everything.

With anthropic and openai, Claude Code works with the models of agent.endpoint instead of your Claude account. agent.endpoint.preset names a ready-made service, or agent.endpoint.url gives the API's base URL:

ymcp pipeline new web --profile work --dir ~/src/web --query "project: WEB #Unresolved" \  --agent openai --endpoint openrouter --model z-ai/glm-5

The API key goes to the system keychain from the wizard, or comes from the variable in the table (agent.endpoint.keyEnv names another). The agent never sees it: Claude Code talks to a gateway on the runner's MCP port with its run's token, and the gateway passes its requests on with the key. For an OpenAI-compatible API the gateway translates them to Chat Completions; for an Anthropic-compatible one it passes them on as they are, so prefer that API where a service has both. agent.model is the model's name at the API; ymcp pipeline NAME check looks for it in the API's list.

Before each turn ymcp fetches origin, so the agent can rebase onto the base branch without fetching itself.

Strategies

After a push the agent writes the PR/MR's title and description in a short turn of its own: ymcp resumes its session with prompts.describe and takes what it passes to the set_change tool, so nothing it said while working ends up there. Put the rules for them (language, format, links) in prompts.describe. An agent that doesn't call the tool is asked once more, then its answer to that turn is the description. Later pushes update the PR/MR the same way, unless someone edited it on the host. "strategy": {"describe": false} opens it from strategy.title and the turn's answer instead. strategy.draft opens them as drafts. For gitlab-mr, strategy.squash and strategy.deleteBranch tick the merge request's "Squash commits" and "Delete source branch" options. The token comes from gh or glab, whichever you are signed in to for that host, or from the system keychain (service ymcp, account vcs:<host>).

CI

After each push the runner watches the CI of the pushed commit: GitHub's check runs and commit statuses, or the GitLab pipeline. That works for every strategy; branch reads the CI of the host origin points at, with the same token. When the CI fails while the run is in review, the agent gets a turn with the failed jobs and the end of their logs, and its answer goes to the issue. After ci.fixes such turns in a row (3) the next failure puts the run into needs input; a turn a person asked for starts the count again. The card's log shows the CI running, passing and failing. "ci": {"watch": false} turns it off.

Agent messages

Everything the agent writes, in YouTrack or on the pull request, starts with a hidden marker and a header:

<!-- ymcp:agent pipeline=backend run=17 msg=3f9a -->@xlsft's agent #17 (backend)
Done: branch BE-123-fix-login, PR https://github.com/acme/api/pull/42

The marker is an HTML comment, so YouTrack, GitHub and GitLab don't show it; ymcp uses it to tell the agent's messages from yours. The header names whose agent it is, the run and the pipeline. When the agent starts on a message, ymcp replies right away with an animated ymcp logo, and later edits that comment into the answer, or into the reason the run stopped.

Feedback and needs input

The agent reacts to comments from you: the profile's YouTrack account and the gh or glab account. Add other logins to feedback.youtrack, feedback.github and feedback.gitlab; comments from anyone else are skipped. Comments that arrive within feedback.debounce (60s) go to the agent together.

A run waits in needs input when the agent asks a question, wants a permission, stays silent for timeouts.silence (10m), runs longer than timeouts.total (2h) or fails. The first reply from an allowed author continues it: a comment in YouTrack or on the pull request, the TUI's inbox, or ymcp pipeline backend answer 17 "…". A permission request takes /approve or /reject; without a reply within timeouts.permission (30m) it is refused. For Claude, /approve allows exactly the calls that were denied for the rest of the run (Bash(<command>), Edit(//<path>), …), never the whole tool; a compound command gets a rule for each of its commands, and a call that can't be spelled as such a rule (a wildcard, a subshell) stays denied.

Three more replies are carried out by ymcp itself, the agent never sees them:

/clear and /compact also work for 30 days after a run ended as done or closed, without moving the issue. "autoCompact": true compacts every run that ends as done or closed. A command runs once: restoring its comment does not run it again.

Notifications

By default, when a run needs input or fails, ymcp shows a system notification with its icon. A click opens the question, the pull request or the issue. It works on macOS, Windows and Linux (with a notification daemon on D-Bus).

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

The events are needs_input, run_failed, review_ready, run_done and runner_stopped. A pipeline can narrow them with "notifications": {"events": [...]} in its JSON.

Prompt presets

The agent's prompts come from a preset: fix (default), bugfix-test-first, feature, refactor, docs or investigate. ymcp pipeline presets shows what each is for. prompts.start, prompts.feedback and prompts.answer replace a preset's texts, with placeholders such as {{issue.id}} and {{branch}}. language (English by default) is the language of everything the agent writes in public: comments, pull requests and commit messages.

The built-in presets are read-only; your own live in presets/ next to the config file. ymcp pipeline presets copy fix mine makes one to change with presets edit mine, and presets save NAME --from PIPELINE keeps the prompts you tuned in a pipeline. rename and rm do what they say. A pipeline copies a preset's texts, so changing or removing a preset never changes a pipeline.

Configuration

ymcp setup and ymcp auth store each profile's name, URL, login and proxy in <config dir>/ymcp/config.json, a file only you can read:

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

The password goes to the system keychain: Keychain on macOS, Secret Service on Linux, Credential Manager on Windows. It falls back to the config file only where no keychain exists.

Environment variables override the stored values of the profile in use. That's handy for CI:

--env FILE loads these variables from a dotenv file (see .env.example).

Behind a VPN? MCP clients often pass an HTTP(S)_PROXY meant for the internet. Such a proxy resolves an internal YouTrack through public DNS and never reaches it. When the proxy comes from the environment and doesn't lead to YouTrack, ymcp connects directly instead and logs why. An explicitly configured proxy is always used.

HTTP

ymcp serve --transport http serves every profile from one process, each at its own path, over Streamable HTTP:

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

The start-up log lists each profile with its URL, e.g. http://127.0.0.1:8090/youtrack-acme. The default profile is also served at /. --profiles a,b serves only those, and --profile a serves just one. A profile that can't sign in is skipped with a warning.

GET /healthz answers {"status":"ok","version":"…"} without the token, for load balancers and monitoring, and ymcp health checks it from the command line. The Docker image uses it as its HEALTHCHECK.

With --token or YMCP_HTTP_TOKEN, every request must carry Authorization: Bearer <token>; set that header in the client's entry for the URL. Without a token the server is open to anyone who can reach it, so keep it on 127.0.0.1 (the default) or set a token; ymcp warns when it listens elsewhere without one.

Docker

The xlsoftware/ymcp image runs the HTTP server for linux/amd64 and linux/arm64. Profiles live in the /config volume. There is no keychain in a container, so passwords are kept in that volume's config file (mode 0600); treat the volume as a secret. The image has the MCP server only; pipelines need a local install.

Add a profile. auth asks for the URL, login and password and checks them before saving:

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

Run the server on port 8090 with a token:

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/ymcpdocker logs ymcp   # lists each profile and its URL

For a single instance without a volume, pass the connection instead: -e YOUTRACK_URL=https://youtrack.example.com -e YOUTRACK_LOGIN=… -e YOUTRACK_PASSWORD=….

Then point clients at a profile's URL with the token, e.g. in Claude Code:

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

or in a JSON config:

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

The image serves stdio too, one instance per client, and that is how the MCP Registry lists it, as io.github.xlsft/ymcp. Clients that install from the registry run:

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

Retries

A busy or restarting YouTrack doesn't fail a tool call right away. ymcp retries up to three times, waiting 0.5, 1 and 2 seconds or as long as Retry-After asks (up to 10 s): on 429 and 503 for any request, and on 502, 504 and dropped connections only for requests that are safe to repeat. A POST that may already have created an issue or comment is never sent twice. Each retry is logged.

Logs

The server logs its start, every client that connects and every tool call. At start it also checks GitHub in the background and, when a newer release is out, logs update available current=0.4.0 latest=0.5.0 run="ymcp update". Each line has the arguments, how long the call took and any error. Sign-ins are logged too. The log goes to stderr, which clients like Claude Desktop keep in their own MCP logs. It is also appended to a file, so you can watch it while a client runs ymcp:

ymcp logs -f

The file is ~/Library/Logs/ymcp/ymcp.log on macOS, ~/.local/state/ymcp/ymcp.log on Linux and %LOCALAPPDATA%\ymcp\logs\ymcp.log on Windows. It rotates at 5 MB.

To log at debug level from a client, add "env": {"YMCP_LOG_LEVEL": "debug"} to its ymcp entry.

Supported clients

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 writes its config back from memory while it runs, which drops edits made meanwhile, so ymcp setup offers to quit it during the change and reopens it afterwards.

ymcp edits each client's config in place and keeps your other servers, keys and comments. It leaves a .ymcp.bak copy next to the original. For any other client, register a stdio server per profile that runs the ymcp binary with --profile <key>:

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

How sign-in works

YouTrack’s OAuth password grant needs a service secret, and regular users don't have one. So ymcp signs in through Hub with the login and password:

1. Read the Hub location and YouTrack service ID from the public /api/config.
2. Submit the Hub login form and keep the session cookie.
3. Run the implicit OAuth flow of the YouTrack web client and take the bearer token from the redirect.

Expired tokens are renewed from the session without resending the password. The password is sent again only when the session itself has expired. A separate Hub-scoped token is fetched lazily for the Hub API, which group members need. Two-factor authentication is not supported yet.

Development

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

Unit tests never touch the network. internal/youtrack/youtracktest emulates YouTrack and Hub, including the login form, the OAuth redirects and token revocation. The tool tests call tools through an in-memory MCP client and check the REST requests they send.

E2E tests (e2e/) start the built binary over stdio against a real YouTrack, by default a fresh one in Docker. They call all 58 tools and delete everything they create. They run in CI on every push, and nightly also against a shared hosted instance.

See CONTRIBUTING.md for the commit and release flow, and the changelog for what each release changed.

License

MIT. Not affiliated with JetBrains; YouTrack is a trademark of JetBrains s.r.o.