Skip to content
Back to search

youtrack-mcp

Model Context Protocol Server for YouTrack - Multi-platform support (ARM64/Apple Silicon + AMD64) with comprehensive API integration

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/tonyzorin/youtrack-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/tonyzorin/youtrack-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tonyzorin--youtrack-mcp/badge.svg)](/listings/tonyzorin--youtrack-mcp)

HTML

<a href="/listings/tonyzorin--youtrack-mcp"><img src="/api/listings/tonyzorin--youtrack-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

You need a YouTrack URL and a [permanent API token](https://www.jetbrains.com/help/youtrack/cloud/manage-permanent-tokens.html).

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"
      ]
    }
  }
}

Same image on GHCR: `ghcr.io/tonyzorin/youtrack-mcp:latest`.

`-i` is required for stdio (without it the container exits immediately). Docker does **not** see Cursor/Claude `env` — pass YouTrack vars with `-e` in `args`. To limit tools, add another `-e` line, for example `ENABLED_TOOLS=get_issue,search_issues,create_issue,add_comment`.

npx (no 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"
      }
    }
  }
}

Requires Node.js 18+ and Python 3.14+. Also published as `@tonyzorin/youtrack-mcp` on GitHub Packages.

Docker from a terminal

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

Tag `latest` is the current stable release (**2.0.0**). Pin `tonyzorin/youtrack-mcp:2.0.0` if you want a frozen image. WIP and PR tags exist for testing; do not use them in production.

Docker Compose (HTTP)

Compose does not attach a client to stdin, so stdio exits after startup. Use streamable HTTP and publish the port:

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

Point Cursor / Claude Code at `http://localhost:8000/mcp`.

Remote HTTP from a terminal:

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 177 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # YouTrack MCP
  2. [![CI](https://github.com/tonyzorin/youtrack-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/tonyzorin/youtrack-mcp/actions/workflows/ci.yml)
  3. [![npm](https://img.shields.io/npm/v/youtrack-mcp-tonyzorin)](https://www.npmjs.com/package/youtrack-mcp-tonyzorin)
  4. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  5. Open-source [Model Context Protocol](https://modelcontextprotocol.io) server for [JetBrains YouTrack](https://www.jetbrains.com/youtrack/). You run it locally (Docker, npx, or Python). It talks to **YouTrack Cloud or Server** over the REST API so Cursor, Claude Desktop, and other MCP clients can search, create, and update issues.
  6. This server shipped in **April 2025**, about six months before JetBrains added a Remote MCP to [YouTrack 2025.3](https://blog.jetbrains.com/youtrack/2025/10/youtrack-introduces-a-remote-mcp-server-and-new-apps-2/) (October 2025). It is not a fork of the official server.
  7. ## Why this still exists
  8. JetBrains’ [official MCP](https://www.jetbrains.com/help/youtrack/cloud/model-context-protocol-server.html) is built **into YouTrack 2025.3+** (Cloud and Server) at `https://<your-instance>/mcp`. New MCP features from JetBrains (OAuth, time tracking, tags, drafts, custom YouTrack apps) live there. Use that if you are on 2025.3 or newer and want the vendor path.
  9. This project is a **process you run**. It calls the YouTrack REST API — the same API that existed before `/mcp`. That is why it still works on **self-hosted Server that has not upgraded to 2025.3**. There is no published minimum YouTrack version; if your instance can issue a permanent token and serve `/api/issues`, this server can talk to it. Article tools need a YouTrack that has the knowledge base.
  10. | | This MCP | Official (2025.3+) |
  11. | --- | --- | --- |
  12. | History | April 2025, before official existed | Shipped in YouTrack 2025.3 (Oct 2025) |
  13. | Where it runs | Your machine (stdio / Docker) | Inside YouTrack (`/mcp`) |
  14. | YouTrack versions | REST API (including Server before 2025.3) | 2025.3 and newer |
  15. | Cursor / Claude Desktop | Native stdio | Remote HTTP, or `npx mcp-remote` |
  16. | Field updates | Simple strings: `update_issue_state("DEMO-123", "In Progress")` | Fetch field schema, then `update_issue` |
  17. | Stick with this for | Older Server, local stdio, attachments, project admin, tool allow/deny lists | New JetBrains MCP features, OAuth, n8n/Zapier `/mcp` URL |
  18. ## Quick start
  19. You need a YouTrack URL and a [permanent API token](https://www.jetbrains.com/help/youtrack/cloud/manage-permanent-tokens.html).
  20. ### Cursor / Claude Desktop (Docker)
  21. ```json
  22. {
  23. "mcpServers": {
  24. "youtrack": {
  25. "command": "docker",
  26. "args": [
  27. "run", "--rm", "-i",
  28. "-e", "YOUTRACK_URL=https://your-instance.youtrack.cloud",
  29. "-e", "YOUTRACK_API_TOKEN=perm-xxx.your-token",
  30. "tonyzorin/youtrack-mcp:latest"
  31. ]
  32. }
  33. }
  34. }
  35. ```
  36. Same image on GHCR: `ghcr.io/tonyzorin/youtrack-mcp:latest`.
  37. `-i` is required for stdio (without it the container exits immediately). Docker does **not** see Cursor/Claude `env` — pass YouTrack vars with `-e` in `args`. To limit tools, add another `-e` line, for example `ENABLED_TOOLS=get_issue,search_issues,create_issue,add_comment`.
  38. ### npx (no Docker)
  39. ```json
  40. {
  41. "mcpServers": {
  42. "youtrack": {
  43. "command": "npx",
  44. "args": ["-y", "youtrack-mcp-tonyzorin"],
  45. "env": {
  46. "YOUTRACK_URL": "https://your-instance.youtrack.cloud",
  47. "YOUTRACK_API_TOKEN": "perm-xxx.your-token"
  48. }
  49. }
  50. }
  51. }
  52. ```
  53. Requires Node.js 18+ and Python 3.14+. Also published as `@tonyzorin/youtrack-mcp` on GitHub Packages.
  54. ### Docker from a terminal
  55. ```bash
  56. docker run --rm -i \
  57. -e YOUTRACK_URL="https://your-instance.youtrack.cloud" \
  58. -e YOUTRACK_API_TOKEN="perm-xxx.your-token" \
  59. tonyzorin/youtrack-mcp:latest
  60. ```
  61. Tag `latest` is the current stable release (**2.1.0**). Pin `tonyzorin/youtrack-mcp:2.1.0` if you want a frozen image. WIP and PR tags exist for testing; do not use them in production.
  62. ### Docker Compose (HTTP)
  63. Compose does not attach a client to stdin, so stdio exits after startup. Use streamable HTTP and publish the port:
  64. ```yaml
  65. services:
  66. youtrack-mcp:
  67. image: tonyzorin/youtrack-mcp:latest
  68. ports:
  69. - "8000:8000"
  70. environment:
  71. YOUTRACK_URL: https://your-instance.youtrack.cloud
  72. YOUTRACK_API_TOKEN: perm-xxx.your-token
  73. TRANSPORT: streamable-http
  74. ENABLED_TOOLS: get_issue,search_issues,get_projects
  75. ```
  76. Point Cursor / Claude Code at `http://localhost:8000/mcp`.
  77. Remote HTTP from a terminal:
  78. ```bash
  79. docker run --rm -p 8000:8000 \
  80. -e YOUTRACK_URL="https://your-instance.youtrack.cloud" \
  81. -e YOUTRACK_API_TOKEN="perm-xxx.your-token" \
  82. tonyzorin/youtrack-mcp:latest \
  83. --transport streamable-http --host 0.0.0.0 --port 8000
  84. ```
  85. ## What you can do
  86. Pass **simple strings** for state, priority, assignee, type, and estimation. Nested `{ "name": "In Progress" }` objects fail.
  87. ```python
  88. search_issues("project: DEMO #Unresolved")
  89. get_issue("DEMO-123")
  90. create_issue(project="DEMO", summary="Login fails on special characters", custom_fields={"Assignee": "admin", "Type": "Bug"})
  91. create_issue(project="DEMO", summary="Sanitize the login form", subtask_of="DEMO-100")
  92. update_issue_state("DEMO-123", "In Progress")
  93. update_issue_priority("DEMO-123", "Critical")
  94. update_issue_assignee("DEMO-123", "admin")
  95. update_issue_type("DEMO-123", "Bug")
  96. update_issue_estimation("DEMO-123", "4h")
  97. add_comment("DEMO-123", "Reproduced on staging")
  98. add_dependency("DEMO-123", "DEMO-124")
  99. ```
  100. **Issues:** search, get, create, update, comments, links (relates / depends / duplicates). Use `subtask_of` on create when the workflow requires a parent; add other links with `link_issues`.
  101. **Custom fields:** dedicated helpers above, plus `update_custom_fields`, batch updates, schema and allowed-value lookup.
  102. **Attachments:** list via `get_issue_raw`, download as base64 (`get_attachment_content`), delete.
  103. **Projects:** list/get, create/update, custom-field schemas, subsystems, versions, builds.
  104. **Users:** current user, lookup, permissions.
  105. **Articles:** get, search, create, update, comments.
  106. **Diagnostics:** `diagnose_workflow_restrictions`, `get_help`.
  107. ## Configuration
  108. | Variable | Required | Description |
  109. | --- | --- | --- |
  110. | `YOUTRACK_URL` | yes | YouTrack base URL (Cloud or Server) |
  111. | `YOUTRACK_API_TOKEN` | yes | Permanent token |
  112. | `YOUTRACK_VERIFY_SSL` | no | SSL verification, default `true` |
  113. | `DISABLED_TOOLS` | no | Comma-separated tools to hide (denylist) |
  114. | `ENABLED_TOOLS` | no | Comma-separated tools to keep; hides all others (allowlist) |
  115. Allowlist wins if both are set. Names are case-insensitive; hyphens and underscores are equivalent.
  116. ```bash
  117. # Hide write tools
  118. export DISABLED_TOOLS="create_issue,update_issue,delete_attachment"
  119. # Read-only subset
  120. export ENABLED_TOOLS="get_issue,search_issues,get_projects"
  121. ```
  122. Self-signed Server: `YOUTRACK_VERIFY_SSL=false`.
  123. ## Development
  124. - [Testing](tests/README.md)
  125. - CI: [`.github/workflows/ci.yml`](.github/workflows/ci.yml)
  126. ## Support
  127. - [GitHub Issues](https://github.com/tonyzorin/youtrack-mcp/issues)
  128. - Telegram: [t.me/tonyzorin](https://t.me/tonyzorin)
  129. MIT. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.