ClaudeにYouTrackのMCPサーバーを接続する手順 — OAuthとトークンの使い分け

YouTrack CloudにはリモートのMCPサーバーが組み込まれており、ClaudeからYouTrackの課題を検索・作成・更新できます。エンドポイントは https://<インスタンス名>.youtrack.cloud/mcp です。

接続方式は、OAuthで自動登録する方法、OAuthクライアントを手動登録する方法、永続トークンを使う方法の3つに分かれます。どれを選ぶかは、使うClaudeの面と、YouTrack側の管理者設定で決まります。

YouTrack MCPサーバーとは何か

YouTrack MCPサーバーは、AIツールにYouTrackの課題を読み書きさせるための窓口です。接続したアカウントの権限がそのまま適用されます。クライアントから見えるのは、認証したユーザーが見られるデータだけです。

課題、記事(ナレッジベース)、プロジェクト、グループ、ユーザー、作業時間の記録に対応する定義済みツールが最初から入っています。別途インストールする必要はありません。

接続前に押さえておく点は2つあります。

• 作成・更新系のツールも含まれるため、確認なしの自動実行は避ける
• クライアントやその提供元は、プロンプトとYouTrackから返ったデータを処理しうる

後者は、会社のデータ取り扱い方針と照らす対象です。

接続方式はClaudeの面とYouTrackの設定で決まる

先に全体像です。「どこから使うか」で最初の分岐が決まります。

CIMD(Client ID Metadata Document)は、クライアントの登録情報をURLで示す仕組みです。YouTrackはOAuthのDynamic Client Registrationに対応していません。そのため、CIMDで自動登録するか、手動で登録したクライアントを使うかのどちらかが必須です。

管理者側の設定は、Administration > Access Management > OAuth Clientsを開き、Allow automatic OAuth client registration via CIMDを有効にします。権限のある人に依頼してください。

Claude CodeからOAuthで接続する

Claude CodeはCIMDを使うサーバーを自動で検出します。管理者がCIMDを有効にしていれば、追加コマンドはURLを渡すだけです。

claude mcp add --transport http youtrack \
  https://my-company.youtrack.cloud/mcp

my-company は自分のインスタンス名に置き換えます。古い myjetbrains.com/youtrack ドメインの環境でも、MCPエンドポイントは同じ形式の youtrack.cloud/mcp を使います。

追加したら、Claude Code内で /mcp を開き、YouTrackを選んでブラウザでの認可を済ませます。認可画面では、YouTrack側でClaudeに許可するアカウントで承認します。

シェルから認可を済ませたいときは、claude mcp login youtrack でも同じOAuthフローを走らせられます。SSH先など、ブラウザを開けない環境では認可URLが表示されます。ローカルのブラウザで開き、リダイレクト後のURLを貼り戻す流れです。

CIMDが使えないときはクライアントを手動登録する

管理者がCIMDを有効にできない、またはCIMDで自動登録できないときは、OAuthクライアントを手動で作ってもらいます。受け取ったクライアントIDとシークレットを、Claude Code側のフラグに渡します。

claude mcp add --transport http \
  --client-id <client-id> --client-secret --callback-port 8080 \
  youtrack https://my-company.youtrack.cloud/mcp

--client-secret を付けると、シークレットをマスク入力で尋ねられます。コールバックポートは、YouTrackのOAuthクライアントに登録するリダイレクトURI(http://localhost:8080/callback の形)のポートと揃えます。

永続トークンで接続する

OAuthの認可フローを通せないクライアント向けの方法です。YouTrackで自分のアカウントの永続トークンを発行します。スコープはYouTrackを選びます。

claude mcp add --header "Authorization: Bearer <token>" \
  --transport http youtrack https://my-company.youtrack.cloud/mcp

トークンはパスワードと同じ扱いです。リポジトリにコミットする .mcp.json に直書きしないでください。Claude Codeでは、設定ファイルの値を ${VAR} 形式の環境変数参照にして、トークンは環境変数側に置く方法があります。

claude.aiのコネクタから接続する

claude.ai(ブラウザ版)では、ディレクトリにあるYouTrackの認証済みコネクタを使います。対象はYouTrack 2026.2.18687以降のYouTrack Cloudで、アドレスが *.youtrack.cloud のサイトです。

手順は次のとおりです。

1. 管理者にCIMDの自動登録を有効にしてもらう
2. ディレクトリでYouTrackコネクタを開いてConnectを押す
3. https://<インスタンス名>.youtrack.cloud の形でサイトのアドレスを入力する
4. YouTrackの認可画面で承認し、Claudeに戻って読み取り依頼で確かめる

独自ドメインを使っているサイトは、元の youtrack.cloud アドレスを入力します。独自ドメインのままではコネクタに通りません。別の道として、カスタムコネクタで登録する方法もあります。

カスタムコネクタで登録する場合

プランで手順が分かれます。

• Team / Enterprise: OwnerまたはPrimary Ownerが、Organization settings > ConnectorsでYouTrackという名前のカスタムコネクタをMCPエンドポイントのURLで追加する。メンバーはCustomize > ConnectorsからConnectする
• 個人プラン: Customize > ConnectorsでプラスボタンからAdd custom connectorを選び、名前とMCPエンドポイントのURLを入れる

OAuthクライアントを手動登録した場合は、Advanced settingsにクライアントID(機密クライアントならシークレットも)を入力します。

カスタムコネクタには大きな前提があります。YouTrackのサイトが公開インターネットから届くことです。Claudeの接続はAnthropicのクラウドから行われるため、社内ネットワークやVPNの内側にあるサイトには届きません。アクセス制限があるサイトでは、Anthropicのクラウドからの接続を許可する必要があります。社内のYouTrackをVPN越しに使う場合、claude.ai側のコネクタは候補から外れ、ローカルのClaude Codeから繋ぐ形になります。

同じ型の接続を別サービスで行う手順は、SonarQubeのMCPサーバーをClaude Codeに接続する手順にあります。自作のリモートMCPを社内システムにつなぐ流れはCoworkカスタムコネクタ自作ガイドで扱っています。

stdioしか受け付けないクライアントにはmcp-remoteを挟む

ローカルのAIツールが、HTTPのリモートMCPに直接つなげず、stdioサーバーしか登録できない場合があります。その場合は、オープンソースのプロキシ mcp-remote をYouTrackの前に置きます。Node.js 18以降と npx が必要です。

永続トークンの構成は次の形です。トークンは AUTH_HEADER という環境変数に Bearer <token> の形で入れておきます。

{
  "mcpServers": {
    "youtrack": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://my-company.youtrack.cloud/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ]
    }
  }
}

OAuthで使う場合は、コールバックポートと、CIMD用の --client-metadata-url または手動登録用の --static-oauth-client-info を引数に足します。Claude Codeのようにリモート接続をそのまま受けるクライアントでは、この構成は不要です。

公開されるツールと、Claudeに頼める作業

定義済みツールは、公式の一覧で6つのグループに分かれています。

課題の作成には順序があります。create_issue の前に get_issue_fields_schema でそのプロジェクトのカスタムフィールドを確認します。必須フィールドがあると作成できないためです。ほかに、自分だけに見える下書きを作る create_draft_issue もあります。

create_issue と add_issue_comment には permittedUsers と permittedGroups という引数があり、閲覧できる範囲を絞れます。「Security Teamだけに見える課題を作って」のように頼めば、Claudeがこの引数を使います。

実際に頼む依頼の例です(いずれも公式のサンプルプロンプトに沿った形)。

• 「Mobile Appプロジェクトで自分に割り当てられた未解決のバグを探して」
• 「WEB-132の状態をIn Progressにして、frontendのタグを付けて」
• 「DEV-203に90分の作業を記録して」

YouTrackには、AIツールから見えないプロジェクトや課題を設定する機能があります。そのため、画面で見える課題がMCPの結果に出ないことがあります。

使えるツールを絞って、更新系に歯止めをかける

YouTrack MCPには更新系のツールが多く含まれます。読み取りだけ使いたい運用なら、YouTrack側とClaude Code側の両方で絞れます。

YouTrack側: URLのクエリパラメータ

エンドポイントのURLに tools を付けると、tools/list で返すツールを列挙したものだけにできます。逆に ignoreTools は、列挙したツールを除外します。

claude mcp add --transport http youtrack \
  "https://my-company.youtrack.cloud/mcp?tools=search_issues,get_issue,get_issue_comments"

URLは引用符で囲みます。? をシェルが展開しないようにするためです。ツール数を減らすと、AIの利用枠を意図せず使い切る事態を防げる、とも説明されています。そのほか、customToolPackages(アプリのカスタムツールを有効にする)と enableToolOutputSchema=true(出力のJSON Schemaを返す)があります。

Claude Code側: 権限ルール

Claude Codeでは、ツール名は mcp__<サーバー名>__<ツール名> の形になります。サーバー名を youtrack にしていれば、権限ルールで読み取りは許可し、更新は毎回確認する構成にできます。例えば次のような形です。

{
  "permissions": {
    "allow": [
      "mcp__youtrack__search_issues",
      "mcp__youtrack__get_issue",
      "mcp__youtrack__get_issue_comments"
    ],
    "ask": [
      "mcp__youtrack__update_issue",
      "mcp__youtrack__add_issue_comment",
      "mcp__youtrack__create_issue"
    ],
    "deny": [
      "mcp__youtrack__log_work"
    ]
  }
}

allowルールのワイルドカードは、mcp__youtrack__* のようにサーバー名までを固定した形でだけ使えます。書き方の詳細はClaude Code MCP権限ルールを参照してください。ツール定義がコンテキストを圧迫する場合は、MCPのトークンオーバーヘッドを抑える設定も効きます。

つまずきの原因と見分け方

Claude Code固有の確認も1つあります。OAuthのトークンが期限切れで拒否されると、/mcp に再認証の案内が出ます。サーバーが途中で落ちたときは、/mcp reconnect all で失敗したサーバーをまとめて再接続できます。詳しくは/mcp reconnect allの記事にあります。

GitHub MCPでも同じ型のOAuth失敗が起きます。切り分けの考え方はGitHub MCPサーバーにOAuth接続できないエラーと共通です。

接続したあとに決めておくこと

最初の確認は、読み取りだけの依頼で済ませます。「自分に割り当てられた課題を探して」で、認証と権限が通っているかが分かります。

そのうえで、更新系を許可する範囲を決めます。許可の単位は、ツール名(update_issue など)と、YouTrack側の可視性の設定です。更新を任せる場合も、ask に入れておけば、課題の更新やコメント投稿の直前に毎回確認が入ります。