MCP server
Every built-in YouTrack tool, and the ones it lacks
ymcp ships every tool of YouTrack’s own MCP server under the same names, arguments and limits, then adds deleting, sprints, attachments, history, time reports and commands. It works with self-hosted instances behind a VPN.
Why it is easy to run
- 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.
ymcp setupregisters itself in Claude, Cursor, VS Code, Zed, Codex, Gemini and more. - A single static binary for macOS, Linux and Windows, with
ymcp updatebuilt in.
Why models get it right
- Fields by display name.
{"State": "In Progress"}is checked against the project before it is sent. - Errors say what to do next: the allowed values, which tool finds the right ID after a 404, that a 403 needs a permission.
- Destructive tools are marked with
destructiveHint, so clients ask before deleting. - Prompts clients offer as slash commands.
Tools marked + are ymcp’s extras; the rest are YouTrack’s own. Red ones delete or bulk-change data, so clients ask first.
Serve only what you need: ymcp serve --tools issues,comments,-delete_issue
Pipelines
A YouTrack search in, pull requests out
A pipeline watches a search and gives each issue it finds to a coding agent, in its own git worktree on a new branch. ymcp pushes the branch, opens the pull or merge request and brings the agent the review comments until the change is merged.
Backlog
The source query found the issue and no run has taken it yet.
Working
The agent works on it in its worktree.
State In ProgressNeeds input
The agent asked a question or wants a permission. You get a notification.
tag needs-inputReview
The branch is pushed and the agent answers review comments.
State FixedDone or closed
The change is merged, or closed without one. The run ends either way.
backend youtrack-work · Claude · /home/dev/code/backend ● running agents 1/1 BACKLOG 3 WORKING 2 NEEDS INPUT 1 REVIEW 2 DONE 2 ──────────────────── ──────────────────── ──────────────────── ──────────────────── ──────────────────── BE-131 ▌ BE-123 #5 BE-127 #6 BE-118 #3 BE-111 #2 Rate limit the ▌ Fix login CSV export Cache keys Flaky migration login endpoint ▌ “Which date forma… test ▌ ⠋ 4m12s writing ⚑ 12m waiting PR #40 ✗ failed 20h BE-133 Pagination for BE-130 #7 BE-120 #4 BE-110 #1 /issues Webhooks Retry jobs Drop legacy endpoints BE-140 ◌ queued ⟳ 1 feedback ✓ done 26h Audit log ←→↑↓ move enter open a answer c cancel d delete o issue p PR r reload s stop e edit i inbox esc back q quit
backend youtrack-work · Claude · /home/dev/code/backend ● running agents 1/1 BAC╭────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ ───│ │ │ backend #6 BE-127 CSV export of the reports State: In Progress Priority: Major │ B│ Assignee: xlsft Estimation: 2d │ R│ stage working ⚑ needs input │ l│ ⎇ be-127-csv-export │ │ Claude · idle · started 1h ago │ B├──────────────────────────────────────────────────────────────────────┬─────────────────────────────────────┤ P│ │ │ /│ Users want to export a report as CSV from the report page: one row │ Log ● running │ │ per issue, with the columns the report shows. │ │ B│ │ 14:30 captured BE-127 CSV export │ A│ Comments · 2 │ 15:17 question Which date format… │ │ │ │ │ Anna Petrova @anna · 50m ago │ │ │ Please also cover the admin reports. │ │ │ │ │ │ ◆ @xlsft's agent #6 (backend) · 13m ago │ │ │ │ Which date format should the CSV export use: ISO 8601 or the │ │ │ │ user's locale? │ │ │ │ │ │ ⚑ needs input · waiting 12m │ │ │ ╭────────────────────────────────────────────────────────────────╮ │ │ │ │ Write a comment, /command, @mention people enter │ │ │ │ ╰────────────────────────────────────────────────────────────────╯ │ │ │ │ │ │ enter reply esc close tab log t transcript ↑↓ scroll ? more │ │ │ │ │ ╰──────────────────────────────────────────────────────────────────────┴─────────────────────────────────────╯
backend youtrack-work · Claude · /home/dev/code/backend ● running agents 1/1 BAC╭────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ ───│ │ │ frontend #1 FE-9 Dark mode State: In Progress Type: Feature Priority: Normal │ B│ Assignee: boris │ R│ stage working ⚑ needs input ⎇ fe-9-dark-mode │ l│ Claude · idle · the runner is stopped · started 3h ago │ │ │ B├──────────────────────────────────────────────────────────────────────┬─────────────────────────────────────┤ P│ │ │ /│ Follow the system theme, with a switch in the settings that │ Log ○ stopped │ │ overrides it. Charts and code blocks need their own dark palette. │ │ B│ │ 12:30 captured FE-9 Dark mode │ A│ Comments · 1 │ │ │ │ │ │ ╭─ Commands ─────────────────────────────────────────────────────╮ │ │ │ │ › /approve allow what the agent asked for │ │ │ │ │ /reject refuse it; the agent goes on without │ │ │ │ │ /compact hide the run's comments and leave a short summary │ │ │ │ │ /clear hide the run's comments; they stay in the history │ │ │ │ │ /cancel cancel the run and close the issue │ │ │ │ ╰────────────────────────────────────────────────────────────────╯ │ │ │ ⚑ needs input · waiting 2h │ │ │ ╭────────────────────────────────────────────────────────────────╮ │ │ │ │ / │ │ │ │ │ │ │ │ │ ╰────────────────────────────────────────────────────────────────╯ │ │ │ ↑↓ choose tab complete esc close │ │ │ │ │ ╰──────────────────────────────────────────────────────────────────────┴─────────────────────────────────────╯
backend youtrack-work · Claude · /home/dev/code/backend ● running agents 1/1 BAC╭────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ ───│ │ │ backend BE-131 Rate limit the login endpoint State: Open Type: Task Priority: Major │ B│ AI: true Assignee: anna flow: frontend │ R│ Stage: Backlog Story points: 3 │ l│ backlog │ ├──────────────────────────────────────────────────────────────────────┬─────────────────────────────────────┤ B│ ╭─ Fields · BE ─────────────╮ │ │ P│ Bots try passwords│ › State Open │ht. │ Run ● running │ /│ │ Type Task │ │ │ │ • at most 5 attemp│ Priority Major │ │ Not taken yet — the runner picks │ B│ • 429 with Retry-A│ AI true │ │ it up from the backlog. │ A│ │ Assignee anna │ │ │ │ Comments · 1 │ Due date — │ │ │ │ │ flow frontend │ │ │ │ Anna Petrova @anna│ Stage Backlog │ │ │ │ Keep the counter│ Story points 3 │ │ │ │ ╰───────────────────────────╯ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ╭────────────────────────────────────────────────────────────────╮ │ │ │ │ Write a comment, @mention people enter │ │ │ │ ╰────────────────────────────────────────────────────────────────╯ │ │ │ │ │ │ ↑↓ choose enter change esc close │ │ │ │ │ ╰──────────────────────────────────────────────────────────────────────┴─────────────────────────────────────╯
ymcp pipelines youtrack-work ⚑ 2 need input ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ╭───────────────────────────────────────────────────────╮ ┃ backend ● running ┃ │ frontend ○ stopped │ ┃ ┃ │ │ ┃ Claude ┃ │ Claude │ ┃ working 2 · review 2 · done 1 ✗ 1 ⚑ 1 ┃ │ working 0 · review 0 · done 0 ⚑ 1 needs input │ ┃ project: BE #Unresolved ┃ │ project: FE #Unresolved │ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ ╰───────────────────────────────────────────────────────╯ ╭╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╮ ┆ ┆ ┆ ┆ ┆ + ┆ ┆ New pipeline ┆ ┆ ┆ ╰╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╯ ←→↑↓ move enter actions o board n new r run s stop e edit L logs c copy R rename d delete i inbox ? more
Inbox ⚑ 2 runs need input › frontend #1 FE-9 Dark mode waiting 2h The agent wants to run: Bash(rm -rf dist). Answer /approve or /reject. ! the runner of frontend is stopped; the answer waits until it starts backend #6 BE-127 CSV export waiting 12m Which date format should the CSV export use: ISO 8601 or the user's locale? ↑↓ move enter reply a quick answer v view run o issue esc back q quit
A pipeline’s board: issues move across the stages while the agent works.
Agents
Each run gets its own MCP server with the same YouTrack tools. Your password never reaches the agent.
Strategies
Where the work goes once the agent is done.
A TUI, or scripts
A board per pipeline and an inbox of runs that wait for you. Or plain commands:
- ymcp pipeline new
- ymcp pipeline NAME check
- ymcp pipeline NAME run -d
Clients
Set up in the clients you already use
ymcp setup adds each YouTrack instance as its own server in the clients you pick, and removes it from the ones you uncheck.
Or run it once for the whole team: ymcp serve --transport http serves every profile on one port, behind a token.
Sign-in
A login and password, nothing to set up
YouTrack’s OAuth password grant needs a service secret that regular users don’t have, so ymcp signs in through Hub instead.
- Read the Hub location and YouTrack service ID from the public
/api/config. - Submit the Hub login form and keep the session cookie.
- Run the web client’s implicit OAuth flow and take the bearer token from the redirect.
Expired tokens are renewed from the session, without resending the password.