YouTrack MCP

Open-source Model Context Protocol server for JetBrains 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.

This server shipped in April 2025, about six months before JetBrains added a Remote MCP to YouTrack 2025.3 (October 2025). It is not a fork of the official server.

Why this still exists

JetBrains’ official MCP 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.

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.

	This MCP	Official (2025.3+)
History	April 2025, before official existed	Shipped in YouTrack 2025.3 (Oct 2025)
Where it runs	Your machine (stdio / Docker)	Inside YouTrack (/mcp)
YouTrack versions	REST API (including Server before 2025.3)	2025.3 and newer
Cursor / Claude Desktop	Native stdio	Remote HTTP, or npx mcp-remote
Field updates	Simple strings: update_issue_state("DEMO-123", "In Progress")	Fetch field schema, then update_issue
Stick with this for	Older Server, local stdio, attachments, project admin, tool allow/deny lists	New JetBrains MCP features, OAuth, n8n/Zapier /mcp URL

Quick start

You need a YouTrack URL and a permanent API token.

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 you can do

Pass simple strings for state, priority, assignee, type, and estimation. Nested { "name": "In Progress" } objects fail.

search_issues("project: DEMO #Unresolved")
get_issue("DEMO-123")
create_issue(project="DEMO", summary="Login fails on special characters", custom_fields={"Assignee": "admin", "Type": "Bug"})

update_issue_state("DEMO-123", "In Progress")
update_issue_priority("DEMO-123", "Critical")
update_issue_assignee("DEMO-123", "admin")
update_issue_type("DEMO-123", "Bug")
update_issue_estimation("DEMO-123", "4h")

add_comment("DEMO-123", "Reproduced on staging")
add_dependency("DEMO-123", "DEMO-124")

Issues: search, get, create, update, comments, links (relates / depends / duplicates).

Custom fields: dedicated helpers above, plus update_custom_fields, batch updates, schema and allowed-value lookup.

Attachments: list via get_issue_raw, download as base64 (get_attachment_content), delete.

Projects: list/get, create/update, custom-field schemas, subsystems, versions, builds.

Users: current user, lookup, permissions.

Articles: get, search, create, update, comments.

Diagnostics: diagnose_workflow_restrictions, get_help.

Configuration

Variable	Required	Description
YOUTRACK_URL	yes	YouTrack base URL (Cloud or Server)
YOUTRACK_API_TOKEN	yes	Permanent token
YOUTRACK_VERIFY_SSL	no	SSL verification, default true
DISABLED_TOOLS	no	Comma-separated tools to hide (denylist)
ENABLED_TOOLS	no	Comma-separated tools to keep; hides all others (allowlist)

Allowlist wins if both are set. Names are case-insensitive; hyphens and underscores are equivalent.

# Hide write tools
export DISABLED_TOOLS="create_issue,update_issue,delete_attachment"

# Read-only subset
export ENABLED_TOOLS="get_issue,search_issues,get_projects"

Self-signed Server: YOUTRACK_VERIFY_SSL=false.

Development

• Testing
• CI: .github/workflows/ci.yml

Support

• GitHub Issues
• Telegram: t.me/tonyzorin

MIT. See LICENSE.