yt-mcp

YouTrack MCP server for Claude Code, GitHub Copilot, Cursor, JetBrains IDEs, n8n, and any MCP-compatible client. Talk to your YouTrack instance in natural language.

Quick start

1. Get a YouTrack permanent token

1. Open YouTrack → Profile → Account Security → Tokens → New token

2. Set scope: YouTrack

3. Grant permissions: Read Issue, Write Issue, Read Project (or just use admin token for full access)

4. Copy the token — it starts with perm:

2. Install in Claude Code

Option A — via CLI (recommended):

Prerequisite: uv is required. Install with: curl -LsSf https://astral.sh/uv/install.sh | sh

claude mcp add youtrack \
  -e YOUTRACK_URL=https://your-instance.youtrack.cloud \
  -e YOUTRACK_TOKEN=perm:your-token-here \
  -- uvx --from git+https://github.com/velesnitski/yt-mcp yt-mcp

Option B — manually edit settings:

Edit ~/.claude.json (global) or .claude/settings.json in your project root (per-project):

{
  "mcpServers": {
    "youtrack": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/velesnitski/yt-mcp", "yt-mcp"],
      "env": {
        "YOUTRACK_URL": "https://your-instance.youtrack.cloud",
        "YOUTRACK_TOKEN": "perm:your-token-here"
      }
    }
  }
}

Troubleshooting: MCP server not found

If Claude Code can't find uvx at startup (e.g., /mcp doesn't show the server), use the full path instead:

"command": "/full/path/to/uvx"

Find the full path with which uvx (typically ~/.local/bin/uvx or /opt/homebrew/bin/uvx).

3. Restart Claude Code

claude

You should see youtrack listed when Claude starts. Try asking: "List my YouTrack projects"

Install in GitHub Copilot (VS Code)

Add to .vscode/mcp.json in your project (or to VS Code User Settings under mcp.servers):

{
  "servers": {
    "youtrack": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/velesnitski/yt-mcp", "yt-mcp"],
      "env": {
        "YOUTRACK_URL": "https://your-instance.youtrack.cloud",
        "YOUTRACK_TOKEN": "perm:your-token-here"
      }
    }
  }
}

Open Copilot Chat (Agent mode) and ask: "List my YouTrack projects"

Install in Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "youtrack": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/velesnitski/yt-mcp", "yt-mcp"],
      "env": {
        "YOUTRACK_URL": "https://your-instance.youtrack.cloud",
        "YOUTRACK_TOKEN": "perm:your-token-here"
      }
    }
  }
}

Install in JetBrains IDEs (IntelliJ, WebStorm, PyCharm, etc.)

Go to Settings → Tools → AI Assistant → Model Context Protocol (MCP) → Add → As JSON:

{
  "youtrack": {
    "command": "uvx",
    "args": ["--from", "git+https://github.com/velesnitski/yt-mcp", "yt-mcp"],
    "env": {
      "YOUTRACK_URL": "https://your-instance.youtrack.cloud",
      "YOUTRACK_TOKEN": "perm:your-token-here"
    }
  }
}

Note: If uvx is not found, use the full path (find with which uvx).

Related MCP server: YouTrack MCP

Multi-instance setup

Connect multiple YouTrack instances to a single MCP server. Each tool gets an optional instance parameter — the LLM picks the right instance from context, or auto-detects it when you paste a YouTrack URL.

Configuration

Set YOUTRACK_INSTANCES to a comma-separated list of instance names, then provide YOUTRACK_{NAME}_URL and YOUTRACK_{NAME}_TOKEN for each:

YOUTRACK_INSTANCES=main,second
YOUTRACK_MAIN_URL=https://main.youtrack.cloud
YOUTRACK_MAIN_TOKEN=perm:xxx
YOUTRACK_SECOND_URL=https://second.youtrack.cloud
YOUTRACK_SECOND_TOKEN=perm:yyy

Adding more instances follows the same pattern:

YOUTRACK_INSTANCES=main,second,third,fourth
YOUTRACK_MAIN_URL=https://main.youtrack.cloud
YOUTRACK_MAIN_TOKEN=perm:xxx
YOUTRACK_SECOND_URL=https://second.youtrack.cloud
YOUTRACK_SECOND_TOKEN=perm:yyy
YOUTRACK_THIRD_URL=https://third.youtrack.cloud
YOUTRACK_THIRD_TOKEN=perm:zzz
YOUTRACK_FOURTH_URL=https://fourth.youtrack.cloud
YOUTRACK_FOURTH_TOKEN=perm:www

Instance names are arbitrary — use whatever makes sense: prod,staging,dev, team1,team2, etc. The name is uppercased to form the env var prefix (dev → YOUTRACK_DEV_URL).

How it works

• No YOUTRACK_INSTANCES — single-instance mode, fully backward compatible. Uses YOUTRACK_URL / YOUTRACK_TOKEN as before.

• First instance falls back to unprefixed YOUTRACK_URL / YOUTRACK_TOKEN if its prefixed vars are not set.

• URL auto-detection — when you paste a YouTrack URL (e.g., https://second.youtrack.cloud/issue/PROJ-123), the server matches the domain to the right instance automatically.

• Explicit instance parameter — every tool accepts an optional instance param to target a specific instance.

• Default — if no instance is specified and no URL is provided, the first configured instance is used.

• Global settings — YOUTRACK_READ_ONLY, DISABLED_TOOLS, and YOUTRACK_MAX_BULK_RESULTS apply to all instances.

Claude Code example

claude mcp add youtrack \
  -e YOUTRACK_INSTANCES=main,second \
  -e YOUTRACK_MAIN_URL=https://main.youtrack.cloud \
  -e YOUTRACK_MAIN_TOKEN=perm:xxx \
  -e YOUTRACK_SECOND_URL=https://second.youtrack.cloud \
  -e YOUTRACK_SECOND_TOKEN=perm:yyy \
  -- uvx --from git+https://github.com/velesnitski/yt-mcp yt-mcp

What it does

Gives MCP clients live access to your YouTrack instance. Instead of opening the YouTrack UI, just ask:

• "What open issues does the Android team have?"

• "Show me OPS-423"

• "Create a bug in the WordPress project: homepage returns 500"

• "Set priority to Critical and assign to John"

• "List all agile boards"

• "What did the DevOps team close this week?"

• "Log 2 hours of development on PROJ-1828"

• "Find articles about deployment"

Available tools (66)

Issues (18)

Attachments (2)

Time tracking (4)

Agile boards & sprints (8)

Projects & users (4)

Discovery & cross-issue analysis (6)

Knowledge Base (8)

Bulk operations (3)

Translation (2)

Priority dashboard & monitoring (9)

Impact analysis (2)

Environment variables

Verify the server works

Check that uv is installed (required for the uvx command):

uv --version

If not installed, get it with:

curl -LsSf https://astral.sh/uv/install.sh | sh

Test the server starts and responds by sending a JSON-RPC initialize request via stdio:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"},"protocolVersion":"2024-11-05"}}' \
  | YOUTRACK_URL="https://your-instance.youtrack.cloud" \
    YOUTRACK_TOKEN="perm:your-token-here" \
    uvx --from git+https://github.com/velesnitski/yt-mcp yt-mcp

A successful response looks like:

{"jsonrpc":"2.0","id":1,"result":{"serverInfo":{"name":"youtrack"},"capabilities":{"tools":{}},...}}

If you see command not found: uvx, install uv first (see above).

Test from a local clone:

cd yt-mcp
pip install -e .
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"},"protocolVersion":"2024-11-05"}}' \
  | YOUTRACK_URL="https://your-instance.youtrack.cloud" \
    YOUTRACK_TOKEN="perm:your-token-here" \
    yt-mcp

List available tools by sending a tools/list request after initialization:

printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"},"protocolVersion":"2024-11-05"}}\n{"jsonrpc":"2.0","id":2,"method":"tools/list"}\n' \
  | YOUTRACK_URL="https://your-instance.youtrack.cloud" \
    YOUTRACK_TOKEN="perm:your-token-here" \
    uvx --from git+https://github.com/velesnitski/yt-mcp yt-mcp

You should see all 66 tools listed.

Setup for Windows

1. Install uv (Python package runner):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Restart your terminal after installation.

2. Get a YouTrack token:

Open YouTrack → Profile → Account Security → Tokens → New token → scope: YouTrack → copy the perm:... token.

3. Add the MCP server to Claude Code:

claude mcp add youtrack `
  -e YOUTRACK_URL=https://your-instance.youtrack.cloud `
  -e YOUTRACK_TOKEN=perm:your-token-here `
  -- uvx --from git+https://github.com/velesnitski/yt-mcp yt-mcp

Note: If Claude Code can't find uvx, use the full path. Find it with where uvx (typically %USERPROFILE%\.local\bin\uvx.exe) and set "command" to that path in your settings.

4. Restart Claude Code and try: "List my YouTrack projects"

Alternative installation methods

From local clone

git clone https://github.com/velesnitski/yt-mcp.git
cd yt-mcp
pip install -e .

Then use in settings:

{
  "mcpServers": {
    "youtrack": {
      "command": "yt-mcp",
      "env": {
        "YOUTRACK_URL": "https://your-instance.youtrack.cloud",
        "YOUTRACK_TOKEN": "perm:your-token-here"
      }
    }
  }
}

Run directly with Python

git clone https://github.com/velesnitski/yt-mcp.git
cd yt-mcp
pip install -e .  # installs mcp and httpx dependencies
yt-mcp

Updating any field

The update_issue tool can update any YouTrack field — not just summary and state. Use the command parameter with YouTrack command syntax:

Priority Critical                          # set priority
Type Bug                                   # set issue type
Deadline 2026-04-01                        # set deadline
Assignee John, Jane                        # multiple assignees
Version 2.5.0                              # set version
Dev Estimate 12                            # set custom numeric field
State In Progress Priority High Type Task  # multiple fields at once
project MOBILE                             # move issue to another project

All changes show a before/after diff and return rollback instructions.

"Set OPS-423 priority to Critical and assign to John" "Move PROJ-100 to the MOBILE project and set deadline to April 1st" "Set dev estimate to 8 and QA estimate to 3 on APP-55"

Query syntax examples

The search_issues tool accepts standard YouTrack search queries:

project: Android state: Open                    # open Android issues
project: DevOps updated: -1w                    # DevOps issues updated in last week
assignee: John priority: Critical               # John's critical issues
#Unresolved project: WordPress                  # unresolved WordPress issues
created: -3d .. today                           # issues created in last 3 days
project: Backend tag: ZTNA                      # Backend issues tagged ZTNA

Issue templates

The server includes built-in templates for creating structured issues. Ask Claude to list them or use them directly:

• "List available templates"

• "Create a bug report in the Android project"

Available templates

Examples

Bug report — just describe the problem naturally:

"Create a bug in MOBILE: app crashes when switching between servers. Steps: connect to server A, tap server B, app freezes and restarts. Happens on Android 14. Critical severity."

Feature request:

"Create a feature request in WEB: add dark mode toggle to the settings page. Should follow system theme by default. Must have priority."

DevOps task:

"Create a devops task in OPS: Deploy new nodes in two additional regions. Need 2 servers per region with monitoring configured. Affected services: free-tier, premium-tier."

Daily standup:

"Create a daily in OPS: Yesterday — fixed monitoring alerts, deployed config update to staging. Today — production rollout, server audit. No blockers."

Research spike:

"Create a spike in MOBILE: Research crash causes on Android 13+. Timebox: 2 days. Need to determine if the issue is in the native layer or Java bridge."

Release checklist:

"Create a release task in MOBILE: version 2.5.0. Changes: new auth flow, config updates, purchase module. Rollback: revert to 2.4.9 via app store."

Claude will automatically use the matching template and fill in the sections from your description.

Setup for claude.ai (web connector)

Use your YouTrack MCP as a custom connector in claude.ai (requires Pro, Max, Team, or Enterprise plan).

1. Deploy the server with OAuth enabled

Set YOUTRACK_OAUTH_URL to your server's public HTTPS URL. Optionally set YOUTRACK_ACCESS_CODE to require a code before connecting:

docker run -d -p 8000:8000 \
  -e YOUTRACK_URL="https://your-instance.youtrack.cloud" \
  -e YOUTRACK_TOKEN="perm:your-token-here" \
  -e YOUTRACK_OAUTH_URL="https://your-server.example.com" \
  -e YOUTRACK_ACCESS_CODE="your-secret-code" \
  yt-mcp --transport sse

Put it behind a reverse proxy (Caddy, nginx, Cloudflare Tunnel) for HTTPS.

Without YOUTRACK_ACCESS_CODE, OAuth auto-approves (no user interaction). With it, users see a simple form to enter the access code before connecting.

2. Add connector in claude.ai

1. Go to claude.ai → Settings → Connectors

2. Click "+ Add custom connector"

3. Enter a name: YouTrack

4. Enter your server URL: https://your-server.example.com

5. Complete the OAuth flow (auto-approved, no user interaction needed)

3. Use it

Start a conversation in claude.ai and ask about your YouTrack issues. All 66 tools are available.

Without YOUTRACK_OAUTH_URL, OAuth is disabled and the server works in standard mode (stdio/SSE without auth) — no changes to existing setups.

Using with n8n, Langchain, and other HTTP clients

By default the server uses stdio transport (for Claude Code). For integration with n8n, Langchain, OpenAI Agents SDK, or any HTTP-based MCP client, start the server in SSE or streamable-http mode:

Start the server with SSE transport

YOUTRACK_URL="https://your-instance.youtrack.cloud" \
YOUTRACK_TOKEN="perm:your-token-here" \
uvx --from git+https://github.com/velesnitski/yt-mcp yt-mcp --transport sse --port 8000

The server will be available at http://localhost:8000/sse.

Start with streamable HTTP transport

YOUTRACK_URL="https://your-instance.youtrack.cloud" \
YOUTRACK_TOKEN="perm:your-token-here" \
uvx --from git+https://github.com/velesnitski/yt-mcp yt-mcp --transport streamable-http --port 8000

The server will be available at http://localhost:8000/mcp.

CLI options

n8n setup

1. Start the server in SSE mode (see above)

2. In n8n, add an MCP Client node (or use the HTTP Request node)

3. Set the MCP server URL to http://localhost:8000/sse

4. The YouTrack tools will be available as actions in your n8n workflows

Make.com setup

1. Start the server in SSE mode (see above)

2. In Make.com, use an HTTP or MCP module to connect to http://localhost:8000/sse

3. Use the poll_changes tool on a schedule to detect new activity:

   • Set query to filter issues (e.g., project: DO)

   • Set since_minutes to match your polling interval (e.g., 5)

4. Route changed issues to other Make.com modules (Slack, email, Jira, etc.)

Docker (for remote / always-on deployments)

Using Docker Hub (recommended):

docker run -d --name youtrack-mcp \
  -e YOUTRACK_URL="https://your-instance.youtrack.cloud" \
  -e YOUTRACK_TOKEN="perm:your-token-here" \
  -p 8000:8000 \
  velesnitski/yt-mcp

The server will be available at http://localhost:8000/sse.

Using docker-compose:

services:
  youtrack-mcp:
    image: velesnitski/yt-mcp
    ports:
      - "8000:8000"
    environment:
      - YOUTRACK_URL=https://your-instance.youtrack.cloud
      - YOUTRACK_TOKEN=perm:your-token-here
    restart: unless-stopped

docker compose up -d

Connect MCP clients to the Docker container:

Claude Code (~/.claude.json):

{
  "mcpServers": {
    "youtrack": {
      "type": "url",
      "url": "http://localhost:8000/sse"
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "youtrack": {
      "url": "http://localhost:8000/sse"
    }
  }
}

Using stdio via Docker (no exposed port):

{
  "mcpServers": {
    "youtrack": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-e", "YOUTRACK_URL=https://your-instance.youtrack.cloud",
        "-e", "YOUTRACK_TOKEN=perm:your-token-here",
        "velesnitski/yt-mcp",
        "--transport", "stdio"
      ]
    }
  }
}

Override transport and port:

docker run -d -p 9000:9000 \
  -e YOUTRACK_URL="..." -e YOUTRACK_TOKEN="..." \
  velesnitski/yt-mcp --transport streamable-http --port 9000

Build from source:

git clone https://github.com/velesnitski/yt-mcp.git
cd yt-mcp
docker build -t yt-mcp .

Security

• Tokens are passed via environment variables — never hardcoded

• In stdio mode, the server has no network exposure (local pipes only)

• In SSE/HTTP mode, the server listens on a network port — bind to 127.0.0.1 if you don't need external access, or use a reverse proxy with authentication for production

• YouTrack API calls use HTTPS (non-HTTPS URLs are blocked unless YOUTRACK_ALLOW_HTTP=1)

• Consider using a token with minimal required permissions (read-only if you don't need create_issue)

• Bulk operations are capped at 100 issues per batch

• Error messages are truncated to prevent leaking internal API details

Logging and privacy

All logs are stored locally on your machine at ~/.yt-mcp/:

• yt-mcp.log — errors and warnings (JSON)

• analytics.log — tool call names, timing, and project codes (JSON)

No data is sent externally unless you explicitly set SENTRY_DSN. Logs never contain tokens, passwords, issue content, or descriptions — only tool names, project codes, and error messages (truncated to 200 chars).

Read-only mode

To disable all write operations (create, update, delete issues/articles, bulk execute, time tracking):

YOUTRACK_READ_ONLY=true

Disable specific tools

Block individual tools by name (comma-separated, case-insensitive):

DISABLED_TOOLS=delete_issue,bulk_update_execute,apply_translations

This removes the specified tools from the MCP server entirely — clients won't see them.

Requirements

Python 3.10+

Check your version:

python3 --version

If not installed or below 3.10:

• macOS (via Homebrew):

  brew install python@3.12

• Ubuntu / Debian:

  sudo apt update && sudo apt install python3 python3-pip

• Windows: download from python.org or use winget install Python.Python.3.12

uv (recommended)

uv is a fast Python package manager. The uvx command (included with uv) is used to run the MCP server without a manual install.

uv --version   # check if already installed

If not installed:

• macOS / Linux:

  curl -LsSf https://astral.sh/uv/install.sh | sh

  Then restart your shell or run source $HOME/.local/bin/env.

• macOS (Homebrew alternative):

  brew install uv

• Windows:

  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

If you prefer not to use uv, see Alternative installation methods for pip-based setup.

License

MIT