Claude Media
Ghidra MCPでClaude Codeにバイナリ解析を任せる設定ガイド
Claude CodeMCPClaude連携チュートリアル

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

Ghidra MCPサーバーをClaude Codeに繋ぎ、逆コンパイルや関数解析をClaudeに任せる手順と、253個のツールを絞り込むLazy Loading設定をまとめました。

読了目安 約14分

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

Ghidra MCPとは何か

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

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

セットアップの前提条件

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

項目要件
Java要件Java 21 LTS(OpenJDK推奨)
ビルドツール要件Apache Maven 3.9以上
Ghidra要件12.1.2、または互換バージョン
Python要件3.10以上(uv推奨。pip + venvでも可)

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

既存の共有Ghidraサーバーに繋ぐ場合は、クライアントとサーバーのバージョンを揃える必要があります。Ghidra 12.1.2のクライアントは、サーバー側が12.1.2または12.0.5以降でないと接続できません。

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があれば保存して閉じ、拡張機能をインストールしてから起動確認まで一気に行います。Ghidra側では、起動後にFile > Configure > Configure All Plugins > GhidraMCPでプラグインを有効化し、Tools > GhidraMCP > Start MCP Serverでサーバーを起動します。既定ではhttp://127.0.0.1:8089/で待ち受けます。

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

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

接続の確認は2段階でできます。Claude Code側はclaude mcp get ghidra、Ghidra MCP側は次のヘルスチェックです。

curl http://127.0.0.1:8089/check_connection

Connected: GhidraMCP plugin running with program '<name>'が返れば、Ghidraとの接続まで通っています。

MCPサーバーの追加はGhidra MCP固有の手順というより、Claude Codeの標準的な流れです。ローカルコマンドを繋ぐ場面はNext.js MCPサーバーをClaude Codeで使う設定ガイドでも同じ形が出てきます。

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

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

用途向くツール構成注意点
未知バイナリの初期調査(読み取り専用)向くツール構成get_metadata / list_methods / get_entry_points / decompile_functionの4つ注意点書き込み系を許可しなくても完結する
関数のリネーム・型付け・コメント作業向くツール構成既定のlisting,function,programグループ注意点リネームは命名規則チェックに引っかかることがある
スクリプト実行・ライブデバッグ向くツール構成GHIDRA_MCP_ALLOW_SCRIPTS=1 + debugger_*ツール群注意点v5.4.1以降は既定で無効。必要なときだけ有効化する

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

253個のツールをどう絞り込むか

Ghidra MCPは253個のツールを一度に広告しません。既定(Lazy Tool Loading)では、接続時にlisting,function,programの3グループ(84エンドポイント+8個の静的ツール)だけを読み込み、残りは実行時にsearch_toolsやload_tool_groupで追加登録します。

この設計には理由があります。253個のツールを一度にtools/listで渡すと、少なくとも1つの主要プロバイダーの上限を超えます。GeminiのAPIは関数定義を状態機械にコンパイルする方式のため、ツール数が多すぎるリクエストを呼び出し前に丸ごと拒否します。

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

これは劣化ではなく完全な失敗で、クライアント側の設定では回避できません。Lazy Tool Loadingはこの制約を踏まえた設計です。

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

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

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

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

export MAX_MCP_OUTPUT_TOKENS=50000
claude

上限を超えた結果は、会話にそのまま貼られるのではなくファイルへ保存されます。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_AUTH_TOKEN効果設定すると、すべてのHTTPリクエストにAuthorization: Bearer <token>が必須になる
GHIDRA_MCP_ALLOW_SCRIPTS効果/run_script_inlineと/run_ghidra_script(Ghidraプロセス上で任意のJavaを実行)を有効化する
GHIDRA_MCP_FILE_ROOT効果ファイルパスを扱うエンドポイントの対象を、指定したディレクトリ配下に制限する

複数のバイナリを同時に開いて作業する場合は、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)で調べた絶対パスに書き換えるのが対処です。

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

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

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

サーバーが起動していないか、ポートが想定と違います。Tools > GhidraMCP > Start MCP Serverでサーバーを起動したか、Edit > Tool Options > GhidraMCP HTTP Serverで設定ポートを確認します。ポートが使用中かどうかは、macOS/Linuxならlsof -i :8089、Windowsならnetstat -ano | findstr :8089で調べられます。

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

まとめ

Ghidra MCPは、GhidraのバイナリRE機能を253個のツールでClaudeに渡すMCPサーバーです。導入の要点は3つあります。まず、python -m tools.setupでビルド・デプロイし、claude mcp addでstdioサーバーとして登録すること。次に、GUI/サービス起動のクライアントではuvのパスを絶対パスにすること。最後に、既定のLazy Tool Loadingと出力トークンの上限を理解して、必要な範囲だけツールと出力を広げることです。

ローカルの単一ユーザー環境で使う限り、追加のセキュリティ設定は不要です。共有サーバーやLAN越しに使う場合だけ、認証トークンとスクリプト実行の許可を明示的に設定してください。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →