Pyghidra Mcp

PyGhidra-MCP - Ghidra Model Context Protocol サーバー

概要

pyghidra-mcp は、堅牢なソフトウェアリバースエンジニアリング（SRE）スイートである Ghidra の分析能力を、インテリジェントエージェントや LLM ベースのツールの世界にもたらす、コマンドライン用の Model Context Protocol（MCP）サーバーです。 Ghidra の ProgramAPI と FlatProgramAPI を pyghidra と jpype を使って Python に橋渡しし、その機能を Model Context Protocol 経由で公開します。

MCP は、言語モデルや VS Code などの開発ツール、自律型エージェントが、構造化されたコンテキストにアクセスし、ツールを呼び出して、インテリジェントに連携できる統一インターフェースです。MCP は、強力な分析ツールと LLM エコシステムをつなぐ架け橋と考えることができます。

pyghidra-mcp によって、Ghidra はインテリジェントなバックエンドとなり、コンテキストが豊富なクエリへの応答、詳細なリバースエンジニアリングタスクの自動化、AI 支援ワークフローへの統合が可能になります。

pyghidra-mcp は、現在 2 つの動作モードをサポートしています。

• CLI 主導の分析と自動化を行う headless モード
• pyghidra-mcp 経由で Ghidra を起動し、実行中の GUI とプログラムのライブ状態を共有する --gui モード

メモ

このベータプロジェクトは現在も活発に開発されています。フィードバック、バグ報告、機能リクエスト、コードの提供をお待ちしています。

また別の Ghidra MCP？

はい、元祖の ghidra-mcp は素晴らしいプロジェクトです。ただし、pyghidra-mcp は異なるアプローチを採用しています。

• 🐍 ヘッドレス優先、GUI にも対応 – 効率的な自動化のために CLI だけで実行することも、GUI 上でのライブナビゲーションや編集が必要な場合に --gui で Ghidra を起動することもできます。
• 🔁 自動化を想定した設計 – LLM、CI パイプライン、再現性のある動作を必要とするツールとの統合に最適です。
• ✅ CI/CD に適合 – クライアントとサーバーの両方のセッションを対象とした、堅牢な単体テストと統合テストを備えています。
• 🚀 素早い起動 – 非同期起動により、バイナリをバックグラウンドで解析している間にサーバーがリクエストの処理を開始できます。最小限のセットアップで、コマンドラインから素早く起動できます。
• 📦 プロジェクト全体の分析 – Ghidra プロジェクト内のすべてのバイナリを並行してリバースエンジニアリングできます。
• 🤖 エージェント対応 – インテリジェントなエージェント主導のワークフローと、大規模なリバースエンジニアリングの自動化を想定して構築されています。
• 🔍 セマンティックコード検索 – ベクトル埋め込み（ChromaDB 経由）を使用して、逆コンパイルされた関数、コメント、シンボルを高速かつ柔軟に検索できます。疑似 C の調査やエージェント主導のトリアージに最適です。

このプロジェクトは、ローカル開発、ヘッドレス環境、テスト可能なワークフローに最適化された、Python を中心とするエクスペリエンスを提供します。

セットアップ図

各要素の接続方法

flowchart LR
    subgraph Clients["Clients"]
        Agent["MCP host / agent"]
        Cli["pyghidra-mcp-cli"]
        User["Ghidra user"]
    end

    subgraph Process["pyghidra-mcp process"]
        Transport["streamable HTTP (recommended)<br/>stdio (local fallback)"]
        Tools["MCP tools"]
        Context["PyGhidra context"]
    end

    Project["Ghidra project<br/>.gpr / .rep"]
    Artifacts["MCP artifacts<br/>ChromaDB + GZF cache"]
    Gui["Ghidra GUI / CodeBrowser<br/>only with --gui"]

    Agent -->|"HTTP (recommended)"| Transport
    Cli -->|"HTTP only"| Transport
    Transport --> Tools
    Tools --> Context
    Context --> Project
    Context --> Artifacts
    Context -.-> Gui
    User -.-> Gui
    Gui -.-> Project

モードの選択

flowchart TD
    Start["What do you need?"]
    Start --> Headless["Agent or automation"]
    Start --> GuiNeed["Live Ghidra GUI control"]
    Start --> Terminal["Interactive terminal client"]

    Headless --> Http["pyghidra-mcp<br/>--transport streamable-http"]
    GuiNeed --> GuiMode["pyghidra-mcp --gui<br/>--transport streamable-http<br/>--project-path project.gpr"]
    Terminal --> HttpServer["Start pyghidra-mcp<br/>--transport streamable-http"]
    HttpServer --> CliMode["Run pyghidra-mcp-cli commands"]

• ヘッドレス MCP：streamable-httpを使用します。Ghidra とそのプロジェクトを、1 つの長時間稼働するサーバーとして起動したままにでき、MCP ホストと CLI クライアントの両方で動作します。
• GUI モード：pyghidra-mcpが Ghidra を起動してプロジェクトを開き、同じ JVM 内の CodeBrowser を操作する追加のツールを公開します。
• CLI クライアント：pyghidra-mcp-cliは HTTP クライアントです。最初にstreamable-httpサーバーを起動し、その後、稼働中のサーバーに対してターミナルコマンドを実行します。
• stdio：HTTP エンドポイントに接続できない MCP ホストに限り、これを使用します。

flowchart TD
    subgraph Clients
        Agent["LLM / MCP host"]
        Cli["pyghidra-mcp-cli"]
        Automation["scripts and CI"]
    end

    subgraph Transports
        Stdio["stdio"]
        Http["streamable-http"]
        Sse["sse legacy"]
    end

    subgraph Server["pyghidra-mcp server"]
        McpServer["MCPServer tool server"]
        Context["PyGhidra context"]
        Indexing["background analysis and Chroma indexing"]

        subgraph Tools["MCP tools"]
            Analysis["decompile, xrefs, bytes, callgraph"]
            Search["symbols, strings, code"]
            ProjectOps["import, delete, metadata, list binaries"]
            Edits["rename function, rename variable, set type, set prototype, set comment"]
            GuiOnly["GUI only: open program, goto, list open programs, set current program"]
        end
    end

    subgraph GhidraRuntime["Ghidra runtime"]
        PyGhidra["pyghidra"]
        Jpype["JPype shared JVM"]
        Project["Ghidra project"]
        Programs["program databases"]
        CodeBrowser["Ghidra GUI / CodeBrowser"]
    end

    Agent --> Http
    Automation --> Http
    Automation --> Sse
    Cli --> Http

    Stdio --> McpServer
    Http --> McpServer
    Sse --> McpServer

    McpServer --> Context
    Context --> PyGhidra
    PyGhidra --> Jpype
    Jpype --> Project
    Project --> Programs
    Context --> Indexing
    Indexing --> Search

    McpServer --> Tools
    Tools --> Context
    GuiOnly -.-> CodeBrowser
    Context -.-> CodeBrowser

目次

• PyGhidra-MCP - Ghidra Model Context Protocol サーバー
  • 概要
  • 別の Ghidra MCP？
  • セットアップ図
    • 各コンポーネントの接続方法
    • モードの選択
  • 目次
  • はじめに
  • エージェント向けに最適化
  • CLI クライアント
    • インストール
    • CLI のクイックスタート
  • プロジェクトの作成、管理、既存プロジェクトを開く
    • 新しいプロジェクトの作成
      • 自己完結型のプロジェクト構成
      • 基本的なプロジェクトの作成
      • カスタムプロジェクトの作成
      • 関連する複数のプロジェクトの作成
    • 既存の Ghidra プロジェクトを開く
      • .gpr ファイルから開く
    • GUI モード
    • 起動時のデフォルト設定と大規模プロジェクト
  • 開発
    • セットアップ
    • テストと品質
  • API
    • ツール
      • 一括操作
      • 読み取り／解析ツール
      • プロジェクト操作
      • 編集／変更ツール
      • GUI 制御ツール（--guiのみ）
  • 使用方法
    • Docker を使用したバイナリのマッピング
    • Streamable HTTP
      • Python
      • Docker
    • Claude Code
    • Codex
    • 標準入力／出力（stdio）
      • Python
      • Docker
    • OpenWeb-UI と MCPO での使用
      • uvxを使用
      • Docker を使用
    • サーバー送信イベント（SSE）
      • Python
      • Docker
  • 参考にしたプロジェクト
  • 貢献、コミュニティ、ソースからの実行
    • 貢献者向けワークフロー

はじめに

Python パッケージとuvを使用して、永続的な Streamable HTTP サーバーを起動します。

uvx pyghidra-mcp \
  --transport streamable-http \
  --project-path /absolute/path/to/ghidra-projects \
  /absolute/path/to/binary

サーバーはhttp://127.0.0.1:8000/mcpで利用できます。サーバーを起動したままにして、MCP クライアントにこの URL を設定してください。以下のClaude CodeおよびCodexの例で、想定される設定を確認できます。

MCP から稼働中の Ghidra GUI を起動して操作するには、streamable-httpと--guiを使用します。

uvx pyghidra-mcp \
  --gui \
  --transport streamable-http \
  --host 127.0.0.1 \
  --port 8000 \
  --project-path /absolute/path/to/ghidra-projects \
  --project-name my_project

重要

--guiはpyghidra-mcpを通じて Ghidra を起動します。すでに実行中の外部 Ghidra インスタンスには接続しません。

または、Docker コンテナとして実行します。

docker run --rm -p 8000:8000 ghcr.io/clearbluejar/pyghidra-mcp

エージェント向けに最適化

pyghidra-mcp は MCP のインターフェースを意図的に絞り込み、エージェントクライアントがツールの検出や引数の選択に費やすトークンを削減します。

• 短いツールの説明：MCP ツールの docstring は簡潔に保たれているため、MCPServer のツールスキーマは小さく、モデルへの送信コストも抑えられます。
• コンテキストの節度：ツールは、プログラム全体のコンテキストをデフォルトで出力するのではなく、対象を絞った構造化データを返します。逆コンパイル、シンボル検索、クロスリファレンスの結果は、1 回の大きな応答ではなく、反復的な分析を支援する形式になっています。
• 関連する場合のみ GUI ツールを使用：open_program_in_gui、list_open_programs、set_current_program、goto などの GUI 専用コントロールは、サーバーを --gui 付きで起動した場合にのみ公開されます。
• CLI は任意：MCP が希望するインターフェースでない場合は、pyghidra-mcp-cli を使うと、よく使われる編集および分析ワークフロー向けにコマンドをグループ化した、HTTP 経由の直接操作用コマンドラインクライアントを利用できます。

これにより、不要なツールやヘッドレスセッションでは使えない GUI 専用コントロールを公開せずに、デフォルトのサーバーを LLM エージェント、IDE との統合、自動化に利用できます。

CLI クライアント

より対話的なコマンドライン操作を行うには、別途提供されている pyghidra-mcp-cli パッケージを使用できます。このパッケージは、実行中の pyghidra-mcp サーバーを操作するための使いやすいインターフェースを提供します。

インストール

CLI クライアントは uv でインストールできます（推奨）。

uvx pyghidra-mcp-cli

または、pip でインストールします。

pip install pyghidra-mcp-cli

CLI を使ったクイックスタート

1. サーバーを起動します（一方のターミナルで）。

pyghidra-mcp --transport streamable-http /bin/ls

2. CLI を使用します（もう一方のターミナルで）。

# List available binaries
pyghidra-mcp-cli list binaries

# Decompile a function
pyghidra-mcp-cli decompile --binary ls main

# Decompile with callees, referenced strings, and cross-references
pyghidra-mcp-cli decompile --binary ls main --callees --strings --xrefs

# Search for symbols (supports regex patterns)
pyghidra-mcp-cli search symbols --binary ls printf -l 10

メモ

CLI は HTTP 経由で pyghidra-mcp に接続するため、コマンドごとに新しい Ghidra プロセスを起動する場合に発生する 10～60 秒の起動オーバーヘッドを避けられます。詳細なドキュメントについては、CLI README を参照してください。

プロジェクトの作成、管理、既存プロジェクトを開く

新しいプロジェクトの作成

ワークフローに応じて、いくつかの方法で新しいプロジェクトを作成できます。

自己完結型のプロジェクト構造

pyghidra-mcp は、各プロジェクトが独自の Ghidra プロジェクトと pyghidra-mcp のアーティファクトを持つ、自己完結型のプロジェクト構造を作成します。これにより、完全な分離と容易なプロジェクト管理が実現します。

基本的なプロジェクトの作成

# Create a new project with default settings
pyghidra-mcp

# Creates: 
$ tree pyghidra_mcp_projects/
pyghidra_mcp_projects/
├── my_project.gpr
├── my_project-pyghidra-mcp
│   ├── chromadb
│   └── gzfs
└── my_project.rep

カスタムプロジェクトの作成

# Create project with custom name and location
pyghidra-mcp --project-path ~/analysis/malware_study --project-name malware_analysis

$ tree ~/analysis/ 
/home/vscode/analysis/
└── malware_study
    ├── malware_analysis.gpr
    ├── malware_analysis-pyghidra-mcp
    │   ├── chromadb
    │   └── gzfs
    └── malware_analysis.rep

関連する複数のプロジェクトの作成

# Create separate projects for different analysis focuses
mkdir ~/reverse_engineering_workspace

# Project for suspicious binaries
pyghidra-mcp --project-path ~/reverse_engineering_workspace/suspicious_binaries --project-name suspicious_analysis

# Project for packed malware  
pyghidra-mcp --project-path ~/reverse_engineering_workspace/packed_malware --project-name packed_analysis

既存の Ghidra プロジェクトを開く

既存の Ghidra プロジェクト（.gpr ファイル）がある場合は、pyghidra-mcp で直接開くことができます。

.gpr ファイルを指定して開く

# Open existing Ghidra project (project name derived from filename)
pyghidra-mcp --project-path ~/existing/ghidra/my_research.gpr

# Result: ~/existing/ghidra/my_research-pyghidra-mcp/
# └── chromadb/, gzfs/ (pyghidra-mcp additions)

GUI モード

MCP の操作対象を、Ghidra に表示されている実行中のプログラムオブジェクトと同じにする場合は、GUI モードを使用します。

• --gui を使用するには、--transport streamable-http が必要です（エイリアスとして --transport http も使用できます）。
• --project-path には、--project-name と組み合わせたプロジェクトディレクトリ、または既存の .gpr ファイルを指定できます。存在しないプロジェクトは自動的に作成されます。
• Ghidra は pyghidra-mcp によって起動されるため、GUI と MCP のトランザクションは同じ JVM 内で実行されます。
• GUI 専用ツールは、--gui を指定して実行した場合にのみ公開されます。

例：

pyghidra-mcp \
  --gui \
  --transport streamable-http \
  --project-path /absolute/path/to/my_research.gpr

次の操作を行う場合は、GUI モードが適しています。

• CodeBrowser でプログラムを開く、または切り替える
• リスティング内で関数またはアドレスに移動する
• 関数の名前を変更したり、コメントを追加したりして、その変更を Ghidra ですぐに確認する

起動時のデフォルト設定と大規模プロジェクト

pyghidra-mcp では、デフォルトで --wait-for-analysis は必要ありません。分析と MCP 側のインデックス作成がバックグラウンドで続く間に、サーバーを起動できます。

これは大規模プロジェクトで重要です。

• バイナリが多数あるプロジェクトでも、サーバーの起動を待たせる必要はありません
• リクエストを受け付ける前にプロジェクトの分析を完了させたい場合は、--wait-for-analysis を利用できます
• 既存の大規模プロジェクトでは、バイナリごとに分析とインデックス作成の完了タイミングが異なることがあります

現在の制限事項：

• Ghidra の分析状態と MCP のインデックス作成状態は別々です
• Ghidra で完全に分析済みのバイナリでも、MCP 側のインデックス作成が完了するまで search_strings やセマンティックな search_code が待機することがあります
• これは既存の大規模プロジェクトを開くときに、より顕著になります

実際の使用では：

• インデックス作成が必要な検索機能の準備が整うまでの間も、そのバイナリに対する逆コンパイル、ナビゲーション、名前変更、コメントの追加は行えます
• 検索機能がすぐに使えることより起動時間を重視する場合は、デフォルトの --no-wait-for-analysis を使用してください
• 起動時間よりすぐに使えることを重視する場合は、--wait-for-analysis を使用してください

開発

このプロジェクトでは、開発とテストを効率化するために Makefile を使用しています。リンティングとフォーマットには ruff を、コード品質の確保には pre-commit フックを使用しています。

セットアップ

1. uv をインストールする：uv がインストールされていない場合は、pip を使用してインストールできます。

   pip install uv
   

   または、公式の uv インストールガイドに従ってください：https://docs.astral.sh/uv/install/

2. 仮想環境を作成して依存関係をインストールする：

   make dev-setup
   source ./.venv/bin/activate
   

3. Ghidra 環境変数を設定する：Ghidra をダウンロードしてインストールし、GHIDRA_INSTALL_DIR 環境変数に Ghidra のインストールディレクトリを設定します。

   # For Linux / Mac
   export GHIDRA_INSTALL_DIR="/path/to/ghidra/"
   
   # For Windows PowerShell
   [System.Environment]::SetEnvironmentVariable('GHIDRA_INSTALL_DIR','C:\path\to\ghidra')
   

テストと品質

Makefile には、テストとコード品質のための複数のターゲットが用意されています。

• make run：MCP サーバーを実行します。
• make test：すべてのテスト（ユニットテストと統合テスト）を実行します。
• make test-unit：ユニットテストを実行します。
• make test-integration：統合テストを実行します。
• make test-integration-fast：pre-commit で使用される軽量な統合スモークテストを実行します。
• make test-integration-gui：GUI 統合テストを実行します。動作する Ghidra のインストールと GUI サポートが必要です。
• make lint：ruff でコードスタイルをチェックします。
• make format：ruff でコードをフォーマットします。
• make typecheck：ruff で軽量な静的チェックを実行します。
• make check：すべての品質チェックを実行します。
• make dev：開発ワークフロー（フォーマットとチェック）を実行します。
• make build：配布用パッケージをビルドします。
• make clean：ビルド成果物とキャッシュを削除します。

推奨される分担：

• pre-commit：ruff、pyright、ユニットテスト、軽量な統合スモークテスト 1 件
• GitHub Actions：Linux のヘッドレス統合テスト一式、Xvfb を使った Linux GUI テスト、CLI テスト、最新の macOS スモークテスト
• 定期実行 CI：古いバージョンの macOS と Ghidra の互換性テスト
• ローカル／手動：環境固有の負荷が高い GUI デバッグとリリース前の健全性確認

API

ツール

LLM が操作を実行し、決定論的な計算を行い、外部サービスと連携できるようにします。

バッチ操作

decompile_function と list_xrefs は、単一のターゲットまたはターゲットのリストを受け付けます。これにより、呼び出しチェーンや複数のシンボルを一度に分析する際の往復回数を減らせます。

// Decompile three functions in one call, with callees and xrefs attached
{
  "binary_name": "firmware.bin",
  "name_or_address": ["main", "init_hardware", "0x08001234"],
  "include_callees": true,
  "include_xrefs": true
}

// Get cross-references for multiple symbols at once
{
  "binary_name": "firmware.bin",
  "name_or_address": ["malloc", "free", "realloc"]
}

項目ごとのエラーはインラインで返されます（ほかのターゲットは引き続き成功します）。

[
  {"name": "main", "code": "void main() { ... }", "callees": ["init_hardware"], "xrefs": [...]},
  {"name": "0xdeadbeef", "code": "", "error": "Function or symbol '0xdeadbeef' not found."}
]

読み取り／分析ツール

• search_code(binary_name: str, query: str, limit: int = 5, offset: int = 0, search_mode: str = "semantic", include_full_code: bool = True, preview_length: int = 500, similarity_threshold: float = 0.0): セマンティックベクトル検索または文字列の完全一致検索を使って、逆コンパイルされた擬似 C コードを検索します。

• list_xrefs(binary_name: str, name_or_address: str | list[str]): 関数、シンボル、またはアドレスへのクロスリファレンスを一覧表示します。単一の対象、または一括検索用のリストを指定できます。

• gen_callgraph(binary_name: str, function_name: str, direction: str = "calling", display_type: str = "flow", condense_threshold: int = 50, top_layers: int = 3, bottom_layers: int = 3, max_run_time: int = 120): 指定した関数の MermaidJS 呼び出しグラフを生成します。「calling」（対象が呼び出す関数）と「called」（対象を呼び出す関数）の両方の方向に対応し、複数の可視化タイプをサポートします。

• decompile_function(binary_name: str, name_or_address: str | list[str], include_callees: bool = False, include_strings: bool = False, include_xrefs: bool = False, timeout_sec: int = 30): 名前またはアドレスを指定して関数を逆コンパイルします。単一の対象、または一括逆コンパイル用のリストを指定できます。詳細レスポンスのフラグを設定すると、各結果に呼び出し先、文字列、またはクロスリファレンスを付加できます。timeout_sec は対象ごとに適用され、各逆コンパイルの試行に個別の制限時間を設定します。

• list_exports(binary_name: str, query: str = ".*", offset: int = 0, limit: int = 25): 指定したバイナリからエクスポートされた関数とシンボルをすべて一覧表示します（query には正規表現を使用できます）。

• list_imports(binary_name: str, query: str = ".*", offset: int = 0, limit: int = 25): 指定したバイナリにインポートされた関数とシンボルをすべて一覧表示します（query には正規表現を使用できます）。

• read_bytes(binary_name: str, address: str, size: int = 32): 指定したアドレスのメモリから生のバイト列を読み取ります。16 進数のアドレスには、0x プレフィックスを付けることも省略することもできます。

• search_strings(binary_name: str, query: str, limit: int = 100): バイナリ内の文字列を検索します。

• search_symbols_by_name(binary_name: str, query: str, functions_only: bool = False, offset: int = 0, limit: int = 25): バイナリ内のシンボルを名前で検索します。大文字と小文字を区別しない正規表現パターン（例：^main$、func.*one）または部分文字列を指定できます。functions_only=True を設定すると、ラベル、変数、その他の関数以外のシンボルを除外できます。

プロジェクト操作

• import_binary(binary_path: str): 指定したパスから現在の Ghidra プロジェクトにバイナリをインポートします。パスがディレクトリの場合、対応するすべてのバイナリファイルを再帰的にスキャンしてインポートし、Ghidra プロジェクト内のディレクトリ構造を保持します。

• list_project_binaries(): 現在の Ghidra プロジェクト内のバイナリを一覧表示します。GUI モードでは、CodeBrowser で現在開いていない場合でも、ディスク上に存在するプロジェクトのバイナリが含まれます。

• list_project_binary_metadata(binary_name: str): 指定したバイナリの詳細なメタデータを取得します。アーキテクチャ、コンパイラ、実行可能ファイル形式、分析指標、ファイルハッシュが含まれます。

• delete_project_binary(binary_name: str): Ghidra プロジェクトからバイナリ（プログラム）を削除します。

編集／変更ツール

• rename_function(binary_name: str, name_or_address: str, new_name: str): 名前またはアドレスを指定して関数名を変更します。GUI モードでは、ライブの Ghidra トランザクションとして実行され、開いているプログラムが更新されます。

• rename_variable(binary_name: str, function_name_or_address: str, variable_name: str, new_name: str): 特定の関数内で、完全一致する名前を指定して関数パラメーターまたはローカル変数の名前を変更します。関数内で名前が見つからない場合、または曖昧な場合、ツールは推測せずエラーを返します。GUI モードでは、ライブの Ghidra トランザクションとして実行され、開いているプログラムが更新されます。

• set_variable_type(binary_name: str, function_name_or_address: str, variable_name: str, type_name: str): 特定の関数内で、完全一致する名前を指定して関数パラメーターまたはローカル変数のデータ型を設定します。関数内で名前が見つからない場合、または曖昧な場合、ツールは推測せずエラーを返します。type_name は、プログラムのデータ型マネージャーに対して Ghidra のデータ型パーサーを使用して解析されます。

• set_function_prototype(binary_name: str, function_name_or_address: str, prototype: str): 完全なシグネチャ文字列から関数プロトタイプを設定します。ツールは必ず Ghidra のネイティブシグネチャーパーサーにプロトタイプを渡し、プロトタイプが無効な場合は、基盤となるパーサーまたは適用時のエラーを返します。

• set_comment(binary_name: str, target: str, comment: str, comment_type: str): 関数／デコンパイラーのコメントまたはリスティングコメントを設定します。リスティングコメントの対象には、アドレス、シンボル、関数を指定できます。サポートされる comment_type の値は decompiler、plate、pre、eol、post、repeatable です。

GUI 制御ツール（--gui のみ）

これらのツールは、pyghidra-mcp を --gui 付きで起動した場合のみ利用でき、プロジェクトデータを直接変更するのではなく、GUI の表示を制御します。

• list_open_programs(): Ghidra GUI で現在開いているプログラムを一覧表示します。
• open_program_in_gui(binary_name: str, new_window: bool = True): プロジェクトのバイナリを CodeBrowser で開きます。デフォルトでは新しい CodeBrowser ウィンドウを開きます。可能な場合は、表示中の CodeBrowser を再利用するよう new_window=false を設定します。
• set_current_program(binary_name: str): 開いているプログラムを、プライマリ GUI ツールコンテキストのアクティブ／現在のプログラムに設定します。
• goto(binary_name: str, target: str, target_type: str): Ghidra GUI でアドレスまたは関数に移動します。target_type は address または function である必要があります。

使用方法

この Python パッケージは PyPI で pyghidra-mcp として公開されており、pip、pipx、uv、poetry、または任意の Python パッケージマネージャーを使用してインストールし、実行できます。

$ uvx pyghidra-mcp --help
Usage: pyghidra-mcp [OPTIONS] [INPUT_PATHS]...

  PyGhidra Command-Line MCP server

Options:
  -v, --version                       Show version and exit.
  -t, --transport [stdio|streamable-http|sse|http]
                                      Transport protocol. SSE is deprecated;
                                      use streamable-http instead. [default: stdio]
  -p, --port INTEGER                  Port for HTTP-based transports. [default: 8000]
  -o, --host TEXT                     Host for HTTP-based transports. [default: 127.0.0.1]
  --project-path PATH                 Directory for a pyghidra-mcp project or an
                                      existing Ghidra .gpr file. [default: pyghidra_mcp_projects]
  --project-name TEXT                 Ghidra project name. Ignored for .gpr paths.
                                      [default: my_project]
  --threaded / --no-threaded          Allow threaded analysis. [default: threaded]
  --max-workers INTEGER               Number of analysis workers; 0 means CPU count.
                                      [default: 0]
  --wait-for-analysis / --no-wait-for-analysis
                                      Wait for initial analysis before starting.
                                      [default: no-wait-for-analysis]
  --gui / --no-gui                    Launch Ghidra GUI in-process and serve MCP
                                      against GUI-open programs. Cannot attach to
                                      an already-running external Ghidra process.
                                      [default: no-gui]
  --list-project-binaries             List ingested project binaries and exit.
  --delete-project-binary TEXT        Delete a project binary by name and exit.
  --force-analysis / --no-force-analysis
                                      Force a new binary analysis each run.
                                      [default: no-force-analysis]
  --verbose-analysis / --no-verbose-analysis
                                      Verbose logging for analysis. [default: no-verbose-analysis]
  --no-symbols / --with-symbols       Turn off symbols for analysis. [default: with-symbols]
  --sym-file-path PATH                Single PDB symbol file for one binary.
  -s, --symbols-path PATH             Local symbols directory.
  --gdt PATH                          Path to GDT files. May be specified multiple times.
  --program-options PATH              JSON file with Ghidra program options.
  --gzfs-path PATH                    Location to store GZFs of analyzed binaries.
  -h, --help                          Show this message and exit.

Docker でバイナリをマウントする

Docker コンテナーを使用する場合、バイナリを含むローカルディレクトリをコンテナーのワークスペースにマウントできます。これにより、pyghidra-mcp でファイルを解析できます。

# Create and populate the new directory
mkdir -p ./binaries
cp /path/to/your/binaries/* ./binaries/

# Run the Docker container with volume mapping
docker run -i --rm \
  -v "$(pwd)/binaries:/binaries" \
  ghcr.io/clearbluejar/pyghidra-mcp \
  /binaries/*

Streamable HTTP

Streamable HTTP は推奨されるトランスポートです。Ghidra のプロセスとプロジェクトを 1 つ稼働状態に保ち、MCP ホストと pyghidra-mcp-cli から利用できるようにすることで、クライアントごとに個別のプロセスを起動するコストを回避します。HTTP 経由で JSON-RPC リクエストを送信します。詳細は仕様をご覧ください。

デフォルトでは、サーバーはクライアント接続用に http://127.0.0.1:8000/mcp でリッスンします。バインドアドレスを変更するには、--host／--port または MCP_HOST／MCP_PORT 環境変数を使用します。クライアントが接続するには、サーバーが稼働している必要があります。

Python

pyghidra-mcp -t streamable-http

Python パッケージのデフォルトは stdio なので、サーバーの起動時には必ず --transport streamable-http を指定してください。

GUI モードではこのトランスポートを使用します。

pyghidra-mcp \
  --gui \
  --transport streamable-http \
  --project-path /absolute/path/to/my_project.gpr

Docker

docker run -p 8000:8000 ghcr.io/clearbluejar/pyghidra-mcp

Claude Code

HTTP サーバーを起動した後、Claude Code に追加します。

claude mcp add --transport http pyghidra-mcp http://127.0.0.1:8000/mcp

プロジェクトで共有する設定にするには、プロジェクトのルートにある .mcp.json に次の内容を追加します。

{
  "mcpServers": {
    "pyghidra-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

type: "http" は必須です。url だけのエントリーは、Claude Code によって stdio サーバーとして扱われます。claude mcp list または /mcp を使用して、接続を確認してください。

Codex

HTTP サーバーを起動した後、~/.codex/config.toml に次の内容を追加します。

[mcp_servers.pyghidra-mcp]
url = "http://127.0.0.1:8000/mcp"

設定を保存した後、Codex を再起動してください。サーバー名は任意です。pyghidra-mcp は Codex に表示される名前です。

Standard Input/Output (stdio)

MCP ホストが HTTP エンドポイントを使用できない場合に限り、stdio を使用してください。親プロセスの標準入力および標準出力ストリームを介して通信するサーバーを起動します。

Python

pyghidra-mcp --transport stdio

サーバーは標準入力と標準出力で通信するため、ターミナルに出力が表示されず、待機しているように見えますが、これは正常です。

Docker

docker run -i --rm ghcr.io/clearbluejar/pyghidra-mcp -t stdio

Docker イメージはデフォルトで Streamable HTTP サーバーを起動するため、イメージ名の後に -t stdio を追加し、インタラクティブな stdio モードには -i を使用してください。

OpenWeb-UI および MCPO での使用

OpenWeb-UI または別の利用側が OpenAPI プロキシを明示的に必要とする場合に限り、MCPO を使用してください。通常の MCP クライアントの場合は、上記の Streamable HTTP エンドポイントに直接接続してください。

https://github.com/user-attachments/assets/3d56ea08-ed2d-471d-9ed2-556fb8ee4c95

uvx の場合

uvx mcpo -- pyghidra-mcp /bin/ls

Docker の場合

uvx mcpo -- docker run -i --rm ghcr.io/clearbluejar/pyghidra-mcp /bin/ls

Server-sent events (SSE)

警告

MCP コミュニティでは、下位互換性のためのレガシーなトランスポートプロトコルと位置付けられています。推奨される代替手段は Streamable HTTP です。

SSE トランスポートでは、クライアントからサーバーおよびサーバーからクライアントへの通信に Server-Send Events を使用して、サーバーからクライアントへのストリーミングを可能にします。詳しくは仕様をご覧ください。

デフォルトでは、サーバーはクライアント接続用に http://127.0.0.1:8000/sse をリッスンします。バインドアドレスを変更するには、--host／--port または MCP_HOST／MCP_PORT 環境変数を使用してください。クライアントが接続するには、サーバーが実行中である必要があります。

Python

pyghidra-mcp -t sse

デフォルトでは、Python パッケージは stdio モードで実行されるため、-t sse を含める必要があります。

Docker

docker run -p 8000:8000 ghcr.io/clearbluejar/pyghidra-mcp -t sse

インスピレーション

このプロジェクトの実装と設計は、次の素晴らしいプロジェクトから着想を得ています。

• GhidraMCP
• semgrep-mcp
• ghidrecomp
• BinAssistMCP

貢献、コミュニティ、ソースからの実行

リバースエンジニアリングの未来は、エージェント駆動で、コンテキストに応じた、スケーラブルなものになると考えています。
pyghidra-mcp は、その未来に向けた一歩です。Ghidra の完全なプロジェクトを AI エージェントや自動化パイプラインから利用できるようにします。

現在も積極的に開発を進めており、フィードバック、課題の報告、貢献を歓迎します。

メモ

フィードバック、バグ報告、機能リクエスト、コードの提供をお待ちしています。

コントリビューターのワークフロー

新しいツールや統合を追加する場合は、次のワークフローをおすすめします。

• 新しい機能であることを示すため、ブランチ名に feature/ のプレフィックスを付けてください。
• pyghidra/tools/ にある既存のツールと同じスタイルおよび構成で、ツールを追加してください。
• StdioClient インスタンスを使ってツールを実行する統合テストを作成してください。tests/integration/ に配置してください。
• tests/integration/test_concurrent_streamable_client.py にツールの呼び出しを追加して、並行テストを拡張してください。
• すべてのテストに合格し、リント規則に準拠することを確認するため、make test と make format を実行してください。

これにより、コードベース全体の一貫性を保ち、リバースエンジニアリングのワークフローに対応する堅牢でスケーラブルなツールを維持しやすくなります。

PyGhidra-MCP Team が ❤️ を込めて作成しました。