JetBrains Youtrack

YouTrack MCP

JetBrains YouTrack 用のオープンソースの Model Context Protocol サーバーです。ローカルで実行します（Docker、npx、または Python）。REST API 経由で YouTrack Cloud または Server と通信するため、Cursor、Claude Desktop、その他の MCP クライアントから課題の検索、作成、更新ができます。

このサーバーは、JetBrains が YouTrack 2025.3（2025 年 10 月）にリモート MCP を追加する約 6 か月前の 2025 年 4 月に公開されました。公式サーバーのフォークではありません。

今もこのプロジェクトが存在する理由

JetBrains の公式 MCP は、YouTrack 2025.3 以降（Cloud および Server）に組み込まれています。https://<your-instance>/mcp から利用できます。JetBrains の新しい MCP 機能（OAuth、時間追跡、タグ、下書き、カスタム YouTrack アプリ）は、こちらにあります。2025.3 以降を利用していて、ベンダー提供の方法を希望する場合は、こちらをお使いください。

このプロジェクトは、自分で実行するプロセスです。YouTrack REST API を呼び出します。これは /mcp より前から存在する API と同じです。そのため、2025.3 にアップグレードしていないセルフホストの Serverでも動作します。公開されている最小 YouTrack バージョンはありません。インスタンスが永続トークンを発行でき、/api/issues を提供できれば、このサーバーから接続できます。記事ツールを使うには、ナレッジベースを備えた YouTrack が必要です。

	この MCP	公式（2025.3 以降）
履歴	2025 年 4 月、公式版の登場前	YouTrack 2025.3 で公開（2025 年 10 月）
実行場所	お使いのマシン（stdio / Docker）	YouTrack 内（/mcp）
YouTrack のバージョン	REST API（2025.3 より前の Server を含む）	2025.3 以降
Cursor / Claude Desktop	ネイティブの stdio	リモート HTTP、または npx mcp-remote
フィールドの更新	シンプルな文字列：update_issue_state("DEMO-123", "In Progress")	フィールドスキーマを取得してから update_issue を実行
この MCP を使い続けるケース	古い Server、ローカル stdio、添付ファイル、プロジェクト管理、ツールの許可／拒否リスト	JetBrains の新しい MCP 機能、OAuth、n8n/Zapier の /mcp URL

クイックスタート

YouTrack の URL と永続 API トークンが必要です。

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

同じイメージは GHCR でも利用できます：ghcr.io/tonyzorin/youtrack-mcp:latest。

stdio には -i が必要です（指定しないとコンテナはすぐに終了します）。Docker から Cursor/Claude の env は参照できません。YouTrack の変数は args 内で -e を使って渡してください。ツールを制限するには、別の -e 行を追加します。例：ENABLED_TOOLS=get_issue,search_issues,create_issue,add_comment。

npx（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"
      }
    }
  }
}

Node.js 18 以降と Python 3.14 以降が必要です。GitHub Packages では @tonyzorin/youtrack-mcp としても公開されています。

ターミナルから Docker を実行する

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

latest タグは現在の安定版リリース（2.0.0）です。イメージを固定したい場合は tonyzorin/youtrack-mcp:2.0.0 を指定してください。テスト用に WIP タグと PR タグもありますが、本番環境では使用しないでください。

Docker Compose（HTTP）

Compose はクライアントを stdin に接続しないため、stdio は起動後に終了します。ストリーミング可能な HTTP を使い、ポートを公開してください。

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

Cursor / Claude Code の接続先として http://localhost:8000/mcp を指定してください。

ターミナルからのリモート HTTP：

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

できること

状態、優先度、担当者、タイプ、見積もりには、シンプルな文字列を渡してください。{ "name": "In Progress" } のようなネストされたオブジェクトは失敗します。

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")

課題： 検索、取得、作成、更新、コメント、リンク（関連／依存／重複）。

カスタムフィールド： 上記の専用ヘルパーに加え、update_custom_fields、一括更新、スキーマおよび許可値の検索に対応しています。

添付ファイル： get_issue_raw で一覧表示、base64 としてダウンロード（get_attachment_content）、削除できます。

プロジェクト： 一覧表示／取得、作成／更新、カスタムフィールドのスキーマ、サブシステム、バージョン、ビルド。

ユーザー： 現在のユーザー、検索、権限。

記事： 取得、検索、作成、更新、コメント。

診断： diagnose_workflow_restrictions、get_help

設定

変数	必須	説明
YOUTRACK_URL	はい	YouTrack のベース URL（Cloud または Server）
YOUTRACK_API_TOKEN	はい	永続トークン
YOUTRACK_VERIFY_SSL	いいえ	SSL 検証。デフォルトは true
DISABLED_TOOLS	いいえ	非表示にするツールをカンマ区切りで指定（拒否リスト）
ENABLED_TOOLS	いいえ	有効にするツールをカンマ区切りで指定。それ以外はすべて非表示になります（許可リスト）

両方を設定した場合、許可リストが優先されます。名前の大文字と小文字は区別されず、ハイフンとアンダースコアは同等です。

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

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

自己署名証明書を使用する Server：YOUTRACK_VERIFY_SSL=false。

開発

• テスト
• CI：.github/workflows/ci.yml

サポート

• GitHub Issues
• Telegram：t.me/tonyzorin

MIT。LICENSE を参照してください。