Ghidra MCPでClaude Codeにバイナリ解析を任せる設定ガイド

Ghidra MCPは、逆コンパイラGhidraの解析機能をMCP経由でClaudeに渡すオープンソースのブリッジです。Claude CodeにMCPサーバーとして登録すると、実行ファイルの逆コンパイルや関数の命名、文字列抽出をチャットの指示だけで進められます。Claude Codeから使うには、Ghidra側のプラグインとPython製のbridge(bridge-mcp-ghidra)の2つを用意し、claude mcp addでbridgeを登録します。本記事は接続手順と、209個あるツールを絞り込む設定、出力サイズの調整までをまとめます。

Ghidra MCPとは何か

Ghidraは実行ファイルを逆コンパイルして解析するリバースエンジニアリングツールです。Ghidra MCPはこのGhidraをMCPサーバーとして公開し、AIツールから関数解析やリネームを操作できるようにするブリッジで、GitHubのbethington/ghidra-mcpが配布しています。209個のMCPツールを持ち、読み取り専用の解析だけでなく、関数名・型のリネーム、構造体の作成、スクリプト実行、P-codeエミュレーション、ライブデバッガ連携まで書き込み系の操作も揃っています。209個は全カタログの数で、GUIプラグイン経由なら205個、ヘッドレスサーバー経由なら190個が提供されます。

解析だけでなく編集もできる点が特徴です。SHA-256による関数ハッシュの一致を使い、バージョンの違うバイナリ間で解析結果(関数名やコメント)を引き継ぐ機能もあります。一度ドキュメント化した関数の情報を、別バージョンの同じバイナリに自動で適用できるということです。

セットアップの前提条件

Ghidra MCPを動かすには次の4つが必要です。

Pythonパッケージマネージャーのuvを推奨しているのには理由があります。Debian系ディストリ(Debian 12以降、Kali、Ubuntu 23.04以降)はシステムのPythonを外部管理化しているため、素のpip installがexternally-managed-environmentエラーで失敗します。uvはプロジェクト専用の.venvを自動で作るため、この制約に引っかかりません。

既存の共有Ghidraサーバーに繋ぐ場合は、クライアントとサーバーのバージョンを揃える必要があります。READMEは、Ghidra 12.1.4のクライアントにサーバー12.1.2か12.0.5以降を求めています。古い共有サーバーは12.1系クライアントの接続先に向かないため、サーバー側を先に上げます。

Claude Codeに接続する

まずリポジトリをクローンし、セットアップスクリプトでビルドとデプロイを行います。

git clone https://github.com/bethington/ghidra-mcp.git
cd ghidra-mcp
python -m tools.setup ensure-prereqs --ghidra-path /path/to/ghidra
python -m tools.setup build
python -m tools.setup deploy --ghidra-path /path/to/ghidra

macOSでHomebrewを使う場合は、Ghidra自体もHomebrewから入れられます。

brew install openjdk@21 maven python ghidra

deployは実行中のGhidraがあれば保存して閉じ、拡張機能をインストールしてから起動確認まで一気に行います。

Claude Code側は、ローカルのstdioサーバーとしてclaude mcp addで登録します。公式ドキュメントが示す基本形は次のとおりです。

claude mcp add [options] <name> -- <command> [args...]

Ghidra MCPに当てはめると、bridgeの起動コマンドを--の後ろに渡す形になります。

claude mcp add --transport stdio ghidra -- \
  /home/you/.local/bin/uv run --directory /path/to/ghidra-mcp bridge-mcp-ghidra

環境変数を渡すときは-eの位置に注意が要ります。Claude Code v2.1.287で、別のポートで待ち受けるGhidraに向けるためGHIDRA_MCP_URLを渡す場面を試しました。-eをサーバー名の前に置くと、-eが複数の値を受け取る指定なのでサーバー名まで環境変数として読まれ、登録に失敗します。

claude mcp add --transport stdio --scope project -e GHIDRA_MCP_URL=http://127.0.0.1:8089 ghidra -- /home/you/.local/bin/uv run --directory /path/to/ghidra-mcp bridge-mcp-ghidra

Invalid environment variable format: ghidra, environment variables should be added as: -e KEY1=value1 -e KEY2=value2

サーバー名を先に置き、-eをその後ろ、--の前に並べると通ります。--scope projectを付けたので、作業ディレクトリに.mcp.jsonが書かれます。

claude mcp add --transport stdio --scope project ghidra -e GHIDRA_MCP_URL=http://127.0.0.1:8089 -- /home/you/.local/bin/uv run --directory /path/to/ghidra-mcp bridge-mcp-ghidra

{
  "mcpServers": {
    "ghidra": {
      "type": "stdio",
      "command": "/home/you/.local/bin/uv",
      "args": ["run", "--directory", "/path/to/ghidra-mcp", "bridge-mcp-ghidra"],
      "env": { "GHIDRA_MCP_URL": "http://127.0.0.1:8089" }
    }
  }
}

登録先のスコープは3種類あり、claude mcp addは既定でlocalスコープ(自分だけ・現在のプロジェクトのみ)に書き込みます。チームで共有するなら--scope projectを付けて.mcp.jsonに書き、全プロジェクトで使うなら--scope userにします。

接続の確認は2段階でできます。Claude Code側はclaude mcp get ghidraで、登録済みのサーバーへ実際に接続して状態を返します。Ghidra側は次のヘルスチェックです。

curl http://127.0.0.1:8089/check_connection

Connected: GhidraMCP plugin running with program '<name>'が返れば、Ghidraとの接続まで通っています。ただしトークンを入れても通るので、保護の確認には使えません。

ここまでのclaude mcp addの流れはGhidra MCPに限りません。ローカルコマンドを繋ぐ別の例はNext.js MCPサーバーをClaude Codeで使う設定ガイドにもあります。

Claudeにバイナリ解析を任せる基本操作

接続できたら、Claudeに「このバイナリのエントリポイントから主要な処理を要約して」のように頼むだけで、Claudeが必要なツールを自分で選んで呼び出します。ただしMCPクライアントによっては、許可するツールを絞りたい場面があります。用途別の目安は次のとおりです。

最小構成の4つが閉じた組み合わせになっているのがポイントです。get_entry_pointsとlist_methodsがアドレスと名前を渡し、decompile_functionがその関数本体を返します。返ってきた本体には呼び出し先の関数名が含まれるので、そこから次のdecompile_function呼び出しにつながります。エントリポイントから追える範囲であれば、この4つだけで調査が完結します。

Claude Code側では、権限ルールでこの構成を固められます。mcp__<サーバー名>__<ツール名>の形で書き、allowは確認なしで呼べるツール、denyは呼べなくするツールです。allowは絞り込みではないため、書き込み系を止めたいときはdenyで名指しします。

{
  "permissions": {
    "allow": [
      "mcp__ghidra__get_metadata",
      "mcp__ghidra__list_methods",
      "mcp__ghidra__get_entry_points",
      "mcp__ghidra__decompile_function"
    ],
    "deny": ["mcp__ghidra__rename_symbol"]
  }
}

サーバー名ghidraは登録時の名前と揃えます。mcp__ghidra__*のようなワイルドカードは、allowでもmcp__<サーバー名>__の後ろに限って使えます。丸括弧で引数を条件にしたmcp__ルールは、読み込み時に無視されます。

209個のツールは、Claude Codeではどこで絞られるか

ツールの絞り込みは、bridgeとClaude Codeの両方で働きます。Claude Codeを使う限り、209個の多さが問題になる場面は限られます。

bridgeが遅延ロードを既定にした理由は、Geminiです。GeminiのAPIは関数定義を状態機械にコンパイルする方式で、全ツールを一度に渡すと呼び出し前にリクエストごと拒否します。

400 INVALID_ARGUMENT
The specified schema produces a constraint that has too many states for serving

Claude Codeにこの制約はありません。Claude Code側のtool searchが外れる条件もあります。

ANTHROPIC_BASE_URLが公式以外のホストを指すとき、ENABLE_TOOL_SEARCH=falseのとき、 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETASを設定したときです。Google CloudのAgent PlatformでClaude 4.5世代より前のモデルを使うときと、Microsoft FoundryのAzureホストでも、ツールを先読みします。外れた構成では、bridgeの遅延ロードだけが絞り込みを担います。

遅延ロードで後から増えたツールは、list_changed通知でClaude Codeに伝わります。対話セッションでは一覧が自動で更新され、-pの非対話モードやAgent SDKでも、ツール一覧は通知で更新されます。通知を受けるストリームが閉じたときは、再接続までは最後に取得した一覧のままです。/mcpから接続し直すと、すぐ最新になります。

通知を無視するクライアントでは、遅延登録されたツールに気づけません。その場合は起動時に--no-lazyを付けるか、環境変数GHIDRA_MCP_LAZY=0を設定して全ツールを最初から読み込みます。

逆に、特定のツール群を毎回見える状態にしたいなら、.mcp.jsonの該当サーバーに"alwaysLoad": trueを足す手があります。ただしtool searchの後回しが外れ、そのサーバーのツールが全部セッション開始時に載ります。bridgeが遅延ロードのままなら、載るのは接続時に登録された分です。

Windowsで設定するときの違い

手順はmacOS・Linuxと同じで、違うのはパスの書き方です。ensure-prereqsとdeployの--ghidra-pathには、"C:\ghidra_12.1.4_PUBLIC"のようにGhidraのインストール先を渡します。

bridgeの登録では、commandをuv.exeの絶対パスにします。C:\\Users\\<you>\\.local\\bin\\uv.exeの形で、JSONではバックスラッシュを2つ重ねます。自分のパスはwhere.exe uvで調べられます。python -m tools.setup preflightを実行すると、解決済みの絶対パスと貼り付け用の設定例も表示されます。

出力サイズとタイムアウトの調整

decompile結果は関数によっては長大になり、Claude Code側の出力上限に触れやすい機能です。ここはGhidra MCPの設定ではなく、Claude Code側の設定で調整します。

Claude Codeは、単一のMCPツール出力が1万トークンを超えると警告を出します。既定の上限は2.5万トークンで、MAX_MCP_OUTPUT_TOKENS環境変数で変更できます。

export MAX_MCP_OUTPUT_TOKENS=50000
claude

上限を超えた結果は、会話にそのまま貼られるのではなくファイルへ保存されます。保存先はセッションのtool-resultsディレクトリで、~/.claude/projects/の下にあります。Claudeはファイルパスだけを受け取り、必要になった時点でそのファイルを読みに行きます。画像を含む結果は、この保存の対象外です。

呼び出しごとのタイムアウトは.mcp.json側のtimeoutフィールド(ミリ秒)で個別に設定できます。未設定の場合はMCP_TOOL_TIMEOUT環境変数、それも未設定なら既定で約28時間という長いタイムアウトになります。

{
  "mcpServers": {
    "ghidra": {
      "command": "/home/you/.local/bin/uv",
      "args": ["run", "--directory", "/path/to/ghidra-mcp", "bridge-mcp-ghidra"],
      "timeout": 600000
    }
  }
}

タイムアウトやMCPサーバーの呼び出しがエラーになる不具合は、Ghidra MCP固有の話ではありません。Agent SDK側では並列呼び出しでタイムアウトの扱いが変わる別のパターンもあり、MCP_TOOL_TIMEOUTを設定しても5分で切れるAgent SDKのMCPツール呼び出しで扱っています。

セキュリティ上の注意

Ghidra MCPはローカル開発を前提に設計されています。既定の構成(127.0.0.1へのバインド、認証なし)は、信頼できる単一ユーザーのワークステーションでは安全です。

ループバックの外に公開する場合は、次の3つの環境変数を先に設定します。サーバーは、トークンなしで非ループバックにバインドしようとすると起動を拒否します。

複数のバイナリを同時に開いて作業する場合は、GHIDRA_MCP_REQUIRE_PROGRAM_SELECTORS=1を設定すると安全です。これを設定すると、対象バイナリを指定しない呼び出しをエラーとして拒否します。設定しない場合、対象を省略した呼び出しは「現在アクティブなプログラム」を暗黙に対象にするため、複数クライアントが同じサーバーを共有していると、意図しないバイナリを書き換えてしまう事故に繋がります。

よくあるつまずき

spawn uv ENOENT / spawn python ENOENT

MCPクライアントがcommandに指定したコマンドを、自分のPATH上で見つけられないときに出ます。systemdのユーザーサービスや.desktopエントリ、Finderから起動したmacOSアプリは、いずれもシェルとは別のPATHで動くため、ターミナルでuvが使えても解決に失敗します。プロセスが立ち上がる前の失敗なので、ログにも何も残りません。which uv(Windowsはwhere.exe uv)で調べた絶対パスに書き換えるのが対処です。登録例の/home/you/.local/bin/uvも、この形です。

"GhidraMCP"メニューがToolsに出てこない

拡張機能が有効化されていないか、インストールが正しく完了していません。File > Install ExtensionsにGhidraMCPが表示されているか確認します。次にFile > Configure > Utility > Configure > GhidraMCPPluginでチェックを入れ、Ghidraを再起動します。mainブランチやv6.0.0のzipでは、File > Configure > Configure All Plugins > GhidraMCPです。

接続がrefusedになる・応答がない

サーバーが起動していないか、ポートが想定と違います。Tools > GhidraMCP > Server Statusで起動状態を見て、止まっていればRestart Serverを選びます。mainブランチやv6.0.0のzipでは、Tools > GhidraMCP > Start MCP Serverで起動します。設定ポートはEdit > Tool Options > GhidraMCP HTTP Serverで確認します。ポートが使用中かどうかは、macOS/Linuxならlsof -i :8089、Windowsならnetstat -ano | findstr :8089で調べられます。

遅延ロードが有効か無効かわからない

READMEの中で、--lazyを既定とする表・解説と、--no-lazyを既定と書く一文が混在しています。後者は許可リストの節にあります。実際のモードはbridgeの起動ログに出るので、そこで確かめます。コマンドライン引数の--lazyと--no-lazyは、環境変数GHIDRA_MCP_LAZYより優先されます。

MCPサーバー導入時のエラーはツールごとに形が違います。似た文脈で起きるHTTP側のエラーはGitHub MCPプラグインがHTTP 400で失敗する原因と対処法でも扱っています。

まとめ

Claude Codeから使うなら、つまずきやすいのはuvの絶対パスと-eの置き場所の2点です。ローカルの単一ユーザー環境なら追加のセキュリティ設定は要らず、LANやサーバー越しにするときだけ認証トークンから先に決めます。