SonarQubeのMCPサーバーをClaude Codeに接続する手順

SonarQube MCP Serverは、SonarSourceが配布する公式のMCP(Model Context Protocol)サーバーです。SonarQube CloudまたはSonarQube ServerのIssue・Security Hotspot・Quality Gate・カバレッジを、Claude Codeから自然文で照会できます。コード検索側はSourcegraphのMCPが担います。

接続はDockerコンテナ1本の起動で済み、claude mcp addにDockerの実行コマンドを渡すだけです。ただし落とし穴が3つあります。

• 接続先で環境変数が違う
• --envに$SONAR_TOKENと書くと、トークンの値そのものが設定ファイルに保存される
• analyze_file_listはSonarQube for IDEが動いていないと使えない

何が呼べるのか — 照会・書き込み・解析の3系統

単体の静的解析ツールではありません。SonarQube側に登録済みの解析結果を、Claude Codeのセッションから検索・参照・更新するためのブリッジです。コンテナイメージはsonarsource/sonarqube-mcpとしてDocker Hubにあります。ツールは性質で3系統に分かれ、どれを有効にするかで運用の安全度が変わります。

「誤検知のIssueに理由を付けてまとめて却下して」のような一括処理を任せるかどうかは、SONARQUBE_READ_ONLYを付けるかどうかで決まります。付け方は、後述の「既定で有効なツールセットと、絞り込み」にあります。

最初の分岐 — SonarQube CloudかServerか

stdioモードのサーバーは、SONARQUBE_ORGが設定されていればCloud、無ければServerとして動きます。環境変数の組み合わせが変わるので、接続先を先に決めます。

起動に失敗したときは、次のメッセージが出ます。

SonarQube server version is not supported, minimal version is SQS 2025.1 or SQCB 25.1

このチェックはServer接続だけが対象で、Cloudには掛かりません。

接続手順 — claude mcp addの前に決めておくこと

SonarQube Cloudへの接続は次のとおりです。

claude mcp add sonarqube \
  --env SONARQUBE_TOKEN=$SONAR_TOKEN \
  --env SONARQUBE_ORG=$SONAR_ORG \
  -- docker run --init --pull=always -i --rm \
     -e SONARQUBE_TOKEN -e SONARQUBE_ORG \
     sonarsource/sonarqube-mcp

SonarQube Serverへの接続です。

claude mcp add sonarqube \
  --env SONARQUBE_TOKEN=$SONAR_USER_TOKEN \
  --env SONARQUBE_URL=$SONAR_URL \
  -- docker run --init --pull=always -i --rm \
     -e SONARQUBE_TOKEN -e SONARQUBE_URL \
     sonarsource/sonarqube-mcp

--より前がclaude mcp add自身のオプション、後ろがコンテナに渡すコマンドです。--envは-eの別名で、v2.1.287のclaude mcp add --helpにも-e, --env <env...>として載っています。設定を手で書きたい場合は、SonarQube MCP Server Configuration Generatorが接続先に応じた設定を出力します。

トークンの値が設定ファイルに書き込まれる

--env SONARQUBE_TOKEN=$SONAR_TOKENの$SONAR_TOKENは、claude mcp addが実行される前にシェルが値に置き換えます。ダミーのトークン(squ_dummy0000)で、プロジェクトスコープ(-s project)を指定して試すと、.mcp.jsonは次の内容になりました。

"env": {
  "SONARQUBE_TOKEN": "squ_dummy0000",
  "SONARQUBE_ORG": "my-org"
}

-s projectの.mcp.jsonはチームで共有するためのファイルで、そのままコミットすればトークンも一緒に公開されます。スコープを省いた既定のlocalスコープなら、保存先は~/.claude.jsonで、チームには共有されません。

チームで共有したいときは、シェルに展開させないようシングルクォートで囲みます。

claude mcp add -s project sonarqube \
  --env 'SONARQUBE_TOKEN=${SONAR_TOKEN}' \
  --env 'SONARQUBE_ORG=${SONAR_ORG}' \
  -- docker run --init --pull=always -i --rm \
     -e SONARQUBE_TOKEN -e SONARQUBE_ORG sonarsource/sonarqube-mcp

同じ条件で試すと、.mcp.jsonには"SONARQUBE_TOKEN": "${SONAR_TOKEN}"と文字のまま入りました。Claude Codeは.mcp.jsonのenv・args・commandの中の${VAR}を、起動時に環境変数から展開します。値が未設定で既定値も無いときは、${VAR}の文字のまま使われて警告が出ます。メンバーはそれぞれ自分のトークンを環境変数に置けばよく、ファイルには秘密が残りません。トークンをバージョン管理にコミットしないこと、設定ファイルでは環境変数の置換を使うことは、SonarSourceのセキュリティ上の注意とも一致します。

既定で有効なツールセットと、絞り込み

既定で有効なのは、analysis・ide・issues・projects・quality-gates・rules・duplications・measures・security-hotspots・dependency-risks・coverage・cagの12種類です。sources・system・webhooks・portfolios・languagesなどは入っていません。ソースの取得(get_raw_source)やWebhookの作成(create_webhook)は、SONARQUBE_TOOLSETSに加えない限りClaude Codeには見えません。projectsは他のツールがプロジェクトキーを引くために必須で、常に有効です。

MCPクライアントは有効なツールすべての名前・説明・入力スキーマを毎回の会話に読み込みます。使わないものを外すと、コンテキストとトークンの消費が減ります。

1つのプロジェクトに固定して使うなら、SONARQUBE_PROJECT_KEYを設定します。定義されているあいだは、各ツールのprojectKey引数が無視され、毎回キーを渡さずに済みます。READMEの環境変数表によると、projectKey引数はスキーマからも消えるので、ツール定義が小さくなり、前述のコンテキスト消費も抑えられます。

書き込みだけを止めたいならSONARQUBE_READ_ONLY=trueを使います。SONARQUBE_TOOLSETSと併用すると両方の絞り込みが重なり、閲覧系のツールセットだけを、書き込み禁止で有効にできます。

旧名のcagとanalysisも使えます。両方を束ねたvortexツールセットが新しい名前で、旧名をvortexなしで使うと起動時に警告が出て、サーバーの説明文にも非推奨の注記が入ります。vortexを使うには、Cloudでは組織にVortexのコンテキスト機能と解析機能の両方の権限が要り、ServerではCAGとA3Sの2つのハブの権限が要ります。

SonarQube for IDEとのブリッジ

analyze_file_listとtoggle_automatic_analysis(自動解析の切り替え)は、起動中のSonarQube for IDE(旧SonarLint)が前提です。MCPサーバーがそこへ接続して動きます。SONARQUBE_IDE_PORTに64120〜64130の範囲でポートを渡すと、MCPサーバーがIDE側の組み込みサーバーに繋がります。VS Code版のSonarQube for IDEには、ポート設定まで済ませるインストールボタンがあります。

Linuxでコンテナとして動かす場合、コンテナはlocalhost上のIDEの組み込みサーバーに届きません。docker runに--network=hostを足してホストのネットワークを共有させます。

Claude Code以外にも、Cursor・VS Code・Windsurf・Zed・GitHub Copilot CLI・Codex CLIなどの設定手順がREADMEにあります。チームでエディタが揃わなくても、同じDockerイメージをクライアントごとの設定に書き換えるだけで使い回せます。

よくあるつまずき

ツールが足りない、機能が動かない

Dockerはイメージをローカルにキャッシュするので、一度取得したsonarsource/sonarqube-mcpは自動では更新されません。docker pull sonarsource/sonarqube-mcpを実行し、Claude Codeを再起動します。docker runに--pull=alwaysを付けておけば、起動のたびに確認されます。

大きなファイルのせいでコンテキストを消費する

ワークスペースをマウントしない場合、analyze_code_snippetはファイル全文をfileContent引数で受け取ります。プロジェクトのディレクトリを/app/mcp-workspaceにマウントすると、プロジェクトからの相対パスをfilePathで渡す方式になります。サーバーがディスクから直接読むため、ファイルの中身はエージェントのコンテキストを通りません。

-- docker run --init --pull=always -i --rm \
   -e SONARQUBE_TOKEN -e SONARQUBE_ORG \
   -v "$PWD":/app/mcp-workspace \
   sonarsource/sonarqube-mcp

Serverで接続はできるのにAPI呼び出しだけ失敗する

原因として疑うのは、USER種別でないトークンを使っていることです。

バージョンが急に変わった

--pull=alwaysは開発環境では便利ですが、CI/CDや共有サーバーでは再現性が崩れます。タグ一覧からsonarsource/sonarqube-mcp:1.19.0.2785のように固定し、--pull=alwaysは外します。

問題の切り分けには、コンテナ内のSTORAGE_PATH/logs/mcp.logが使えます。ファイルへのログ出力を止めるならSONARQUBE_LOG_TO_FILE_DISABLED=trueです。

匿名テレメトリとライセンス

既定で匿名の利用データがSonarSourceへ送られます。ソースコードとIPアドレスは収集対象外で、止めるにはTELEMETRY_DISABLED=trueを環境変数に足します。ライセンスはSONAR Source-Available License v1.0(SSAL)で、非競合目的(Non-Competitive Purpose)の利用が許可されています。利用はSonarQube CloudのTerms of ServiceまたはSonarQube ServerのTerms and Conditionsにも従います。結果データの用途は、自社のソフトウェア開発の目的に限られます。

まとめ

接続そのものはclaude mcp add1回で終わります。最初に決めるのは、トークンの保存スコープと、書き込み系ツールをClaude Codeに見せるかどうかの2点です。

MCPサーバーのスコープや.mcp.jsonの基本は、Claude Code MCP設定ガイドにあります。Claude CodeをCI上で動かす前提は、Claude CodeをGitHub Actionsに組み込むにあります。