pyghidra-lite

pyghidra-lite

Ghidra ベースのリバースエンジニアリング向け、トークン効率に優れた MCP サーバーです。Swift、Objective-C、Hermes に対応し、ELF、Mach-O、PE バイナリを解析できます。逆コンパイル、逆アセンブル、呼び出しと値のフローの追跡、データ型の復元、アドレスのファイルオフセットへの対応付けが可能です。Linux、macOS、Windows で動作し、リバースエンジニアリング用スキルを同梱した Claude Code プラグインとして提供されます。

要点： 軽量でセキュリティを最優先した Ghidra MCP です。デフォルトでは読み取り専用で、解析ツールがバイナリやサーバー設定を変更することはありません（設定はプロセスの実行中、固定されます）。書き込みを行う唯一のツール annotate（名前変更／コメント／プロトタイプ）はオプトイン（--allow-write）で、人による確認が必要です。変更を確定する前に、MCP の確認プロンプトを通じてすべての変更を承認する必要があります。また、クライアントが確認を求められない場合は、安全側に倒して失敗します。読み取り専用の安全性を損なうことなく、監督のもとで解析結果を保持できるエージェントを利用できます。

クイックスタート

1. 前提条件

64 ビット版 JDK 21 以降と Ghidra 11.x または 12.x が必要です（Ghidra 12.1.2 と JDK 21 でテスト済み）。

# macOS
brew install openjdk@21
brew install ghidra

# Ubuntu/Debian
sudo apt install openjdk-21-jdk
# Download Ghidra from https://ghidra-sre.org

# Arch Linux
sudo pacman -S jdk21-openjdk
yay -S ghidra

Homebrew でインストールした Ghidra（brew install ghidra）、または /opt/ghidra や ~/ghidra にインストールした Ghidra は自動的に検出されます。それ以外の場所（Windows のインストールを含む）では、展開した ghidra_<version>_PUBLIC フォルダーを GHIDRA_INSTALL_DIR に指定してください。

2. インストール — いずれかを選択

Claude Code プラグイン（Claude Code におすすめ）

MCP サーバーとリバースエンジニアリング用スキルを一度にインストールし、Ghidra のディレクトリを尋ねます。PATH 上に uv が必要です。

/plugin install pyghidra-lite --marketplace johnzfitch/pyghidra-lite

任意の MCP クライアント

パッケージをインストールしてから、クライアントに追加します（Claude Code：プロジェクト内の .mcp.json または ~/.claude.json。その他のクライアント：MCP の設定を参照）。

pip install pyghidra-lite

{
  "mcpServers": {
    "pyghidra-lite": {
      "command": "pyghidra-lite"
    }
  }
}

3. 環境を確認する

pyghidra-lite doctor   # Ghidra, JDK, decompiler, project dir, locks; exits 1 on problems

ヒント

シェルでのインストールを行わないプラグインユーザーは、uvx pyghidra-lite doctor で同じ確認を実行できます。

4. 使用する

You: Analyze the binary at /path/to/binaries/app

Claude: [calls load, info, code...]

インストール

Claude Code プラグイン

MCP サーバー（uvx で実行するため、uv が PATH に含まれている必要があります）と pyghidra-lite:reverse-engineering ワークフロースキルをインストールし、Ghidra ディレクトリ、キャッシュディレクトリ、任意のパス制限、および annotate を許可するかどうかを尋ねます。

/plugin install pyghidra-lite --marketplace johnzfitch/pyghidra-lite

• Claude Code 2.1.275 より前のバージョンでは、最初に /plugin marketplace add johnzfitch/pyghidra-lite を実行してから、/plugin install pyghidra-lite@pyghidra-lite を実行してください。
• このプラグインはパッケージのバージョンを厳密に固定し、セッションごとに 1 つのサーバーを実行します。プラグインを更新した後は、/reload-plugins を実行する（または新しいセッションを開始する）と切り替わります。
• 後から設定を変更するには、/config を開いてください。

警告

.mcp.json または ~/.claude.json に手動で pyghidra-lite のエントリも追加している場合は、それを削除してください — 削除しないと、すべてのツールが 2 回ずつ表示されます。

PyPI（推奨）

pip install pyghidra-lite

Arch Linux（AUR）

yay -S python-pyghidra-lite

ソースから

git clone https://github.com/johnzfitch/pyghidra-lite
cd pyghidra-lite
pip install -e .

MCP の設定

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）に追加します。

{
  "mcpServers": {
    "pyghidra-lite": {
      "command": "uvx",
      "args": ["pyghidra-lite"]
    }
  }
}

初回実行時に uvx が PyPI から pyghidra-lite を自動インストールします。Ghidra は自動検出されます。必要に応じて、env に GHIDRA_INSTALL_DIR を設定してください。

{
  "mcpServers": {
    "pyghidra-lite": {
      "command": "uvx",
      "args": ["pyghidra-lite"],
      "env": {
        "GHIDRA_INSTALL_DIR": "/path/to/ghidra"
      }
    }
  }
}

Claude Code

プロジェクトに .mcp.json を作成します（グローバルに設定する場合は ~/.claude.json）。

{
  "mcpServers": {
    "pyghidra-lite": {
      "command": "pyghidra-lite"
    }
  }
}

直接モード（プロキシをスキップ）

単一セッションでの使用またはデバッグを行う場合は、サーバーを直接実行します。

{
  "mcpServers": {
    "pyghidra-lite": {
      "command": "pyghidra-lite",
      "args": ["serve"]
    }
  }
}

Ghidra のパスを明示する場合

{
  "mcpServers": {
    "pyghidra-lite": {
      "command": "pyghidra-lite",
      "args": [
        "serve",
        "--ghidra-dir", "/path/to/ghidra"
      ]
    }
  }
}

特定のパスに制限する場合

デフォルトでは、pyghidra-lite は任意のパスからバイナリを読み込めます（権限は MCP クライアントが処理します）。アクセスを制限するには --restrict-path を使用します。

{
  "mcpServers": {
    "pyghidra-lite": {
      "command": "pyghidra-lite",
      "args": [
        "serve",
        "--restrict-path", "/home/user/binaries",
        "--restrict-path", "/opt/targets"
      ]
    }
  }
}

HTTP トランスポートの共有（ネットワークアクセス）

HTTP/SSE トランスポートは共有され、DNS リバインディング保護（Host/Origin の検証）が適用されます。ループバック以外のアドレスにバインドするには、さらに --restrict-path とベアラートークンの両方が必須です。

pyghidra-lite serve -t streamable-http --host 0.0.0.0 \
  --restrict-path /opt/targets \
  --auth-token "$PYGHIDRA_LITE_AUTH_TOKEN" \
  --allowed-host re.example.com:8000   # if fronted under another hostname

クライアントは、各リクエストに Authorization: Bearer <token> を付けて送信します。リモートアクセスの場合は、リバースプロキシで TLS を終端してください。

ツール（9）

pyghidra-lite は、読み取り専用の解析ツール 8 個と、オプトイン方式の書き込みツール 1 個を提供します。いずれもフォーマット（ELF/Mach-O/PE）と言語（Swift/ObjC/Hermes）を自動検出します。

ツール	用途	主なパラメーター
load	バイナリをインポートして解析	path、profile?、fresh?、bootstrap?、bootstrap_mode?
delete	バイナリを削除し、ジョブをキャンセル	name
binaries	バイナリとジョブの状態を一覧表示	jobs?、rank_sources?
info	バイナリの概要	binary、detail?（summary/full/format/sections/entropy）
functions	関数、インポート、エクスポートを一覧表示／検索	binary、query?、type?（all/swift/objc/imports/exports/types/got/dylibs）、limit?
code	デコンパイル、逆アセンブル、p-code、バイト列	binary、target、what?（decompile/asm/pcode/bytes/string）、cfg?
xrefs	参照とコールグラフ	binary、target、direction?、depth?、diff?
search	文字列、バイト列、シンボル、データ型を検索	binary、query、type?（strings/symbols/bytes/all/blob/extract/types）、mode?、bg?
annotate 🔒	名前の変更／コメントの追加／プロトタイプの設定	binary、target、action、name?/comment?/prototype?

🔒 書き込みを行うツールは annotate のみです。サーバーの起動時に --allow-write が指定されない限り無効であり、変更を確定する前に毎回インタラクティブな確認（MCP エリシテーション）が必要です。確認できないクライアントにはプレビューのみが表示されます。書き戻しを参照してください。

例

# Import and analyze
load("/path/to/binary", profile="fast")

# Version-track from a prior build, including synthetic IDs for unnamed code
load("/path/to/new.bin", profile="deep", bootstrap="old.bin", bootstrap_mode="all")

# Get overview with full triage
info("mybinary", detail="full")

# List Swift functions
functions("mybinary", type="swift")

# Decompile with CFG
code("mybinary", "main", cfg=True)

# Search strings in background
search("mybinary", ["password", "api_key"], bg=True)

# Get cross-references
xrefs("mybinary", "malloc", depth=2)

# Value flow: SSA p-code, grouped by basic block; each value is defined once
code("mybinary", "parse_header", what="pcode")
# ...or just where one argument's value goes (forward slice; ~10x smaller on real code)
code("mybinary", "parse_header,param_2", what="pcode")

# Raw bytes plus where they live in the file (for patching)
code("mybinary", "0x4011a0,64", what="bytes")   # -> hex, ascii, file_offset, block

# Recovered struct layouts / enums / typedefs
search("mybinary", "sockaddr", type="types")

自動検出

すべてのツールが以下を自動検出します。

• フォーマット：ELF、Mach-O、PE
• 言語：Swift、Objective-C、Hermes/React Native
• ランタイム：Bun、Node.js、Electron、PyInstaller

フォーマットや言語に固有の機能にアクセスするには、type と detail のパラメーターを使用してください。

ブートストラップモード

• bootstrap_mode="named"：意味のあるソース名のみを転送します（デフォルト）。
• bootstrap_mode="all"：転送時に、ソースの FUN_* 関数にも安定した合成ラベルを割り当てます。意味よりも一意性が重要となる、大規模なバージョン間ブートストラップワークフローで役立ちます。

書き戻し

デフォルトでは pyghidra-lite は読み取り専用です。バイナリを変更するツールはありません。エージェントが調査結果を保存できるようにするには（関数名の変更、コメントの追加、プロトタイプの修正など）、--allow-write を指定してサーバーを起動します。

pyghidra-lite serve --allow-write          # or PYGHIDRA_LITE_ALLOW_WRITE=1

これで annotate ツールが使用可能になります。

annotate("mybinary", target="FUN_00401000", action="rename", name="parse_header")
annotate("mybinary", target="parse_header", action="comment", comment="validates the v2 header")
annotate("mybinary", target="parse_header", action="prototype", prototype="int parse_header(char *buf, int len)")

すべての呼び出しには人間による確認が必要です。サーバーは変更内容 old -> new を正確に示す MCP の確認プロンプトを送信し、承認された場合にのみ変更を確定します。サーバーが --allow-write を指定せずに起動された場合、ツールは処理を拒否します。MCP クライアントが確認プロンプトに対応していない場合、ツールは applied: false のプレビューを返し、何も書き込みません（フェイルクローズ）。確認済みの変更は単一の Ghidra トランザクション内で書き込まれ、ディスク上のプロジェクトに保存されます。

監査ジャーナル。 MCP の確認プロンプトでは最終的にクライアントを信頼することになるため（自律型の「自動承認」クライアントは自ら承認できます）、すべての書き込みはプロジェクトの隣にある annotate_audit.jsonl に記録されます。拒否された試行や失敗した試行もすべて記録されます。各行には old -> new が記録されるため、このジャーナルは説明責任を果たすための記録であると同時に、変更を元に戻すためのログにもなります。記録が急増した場合は、自動エージェントが大量の処理を繰り返している兆候です。サーバーは書き込み量の増加に応じて警告（ctx.warning）も出します。ジャーナルはフェイルクローズで強化されています。書き込みは適用前に記録され（記録できない場合は確定されません）、ファイルは 0o600 で作成され、O_NOFOLLOW を指定して開かれます（シンボリックリンクされたジャーナルは拒否されます）。また、サイズに応じてローテーションされるため、際限なく増大することはありません。

分析プロファイル

プロファイル	用途
fast	迅速なトリアージ。処理の遅いアナライザーを20個無効にします（デフォルト）
default	バランスの取れた、Ghidra による完全な分析
deep	難読化されたコードの徹底的な分析

MCP のタイムアウト制限内に収めるため、サーバーのデフォルトは fast です。必要に応じて load(fresh=True) を使うと、より詳細な分析を実行できます。

# Default import uses fast profile
load("/path/to/binary")

# Re-analyze with deep profile
load("/path/to/binary", profile="deep", fresh=True)

トークン効率

pyghidra-lite は、トークンの使用量を最小限に抑えるよう設計されています。

• コンパクトな JSON - 結果はインデントなしでシリアライズされ、呼び出しごとに1つのテキストブロックとして返されます （サンプルバイナリで全ツールを測定したところ、整形出力と比べて文字数が33％減少）
• 空のフィールドなし - false のフラグ、空のタグリスト、null のコンテキストは省略されます
• ダンプではなくスライス - code("func,var", what="pcode") は、値が流れ込む演算のみを返します （ws2_32.dll の WSAStartup では、約1.9K文字。完全なリストでは約22K文字）
• デフォルトでコンパクトな出力 - functions(binary, type="all") は、最小限の {name, addr} ペアを返します
• 詳細表示は必要に応じて有効化 - 必要な場合にのみ info(detail="full")、code(cfg=True)、またはより詳細な type／what モードを使用します
• 進捗表示 - 大規模なインポートでは、10％ごと、または60秒ごとに進捗を報告します
• 文字列の切り詰め - 長い文字列は500文字で切り詰められます

アーキテクチャ

デフォルトでは、pyghidra-lite は軽量な stdio プロキシ（約 10MB）として動作し、永続的な共有 HTTP バックエンド（JVM 約 500MB）に転送します。複数のセッションでそれぞれ JVM を起動するのではなく、1 つの JVM を共有します。

Claude Code session 1 ──stdio──> proxy ──┐
Claude Code session 2 ──stdio──> proxy ──┼──HTTP──> shared backend (1 JVM)
Claude Code session 3 ──stdio──> proxy ──┘        localhost:19101

プロキシは初回使用時にバックエンドを自動起動します。また、ファイルロックとポートチェックにより、複数のプロキシが重複して起動するのを防ぎます。バックエンドは pyghidra-lite stop を実行するまで動作し続けます。30 分間アイドル状態のバイナリはメモリからアンロードされ（直近の 2 つは読み込み状態を維持）、ディスクから透過的に再読み込みされます。

重要

プロキシは、すでに待ち受けているバックエンドがあれば、そのバージョンにかかわらず再利用します。pyghidra-lite の アップグレード後は、pyghidra-lite stop を実行して、次のセッションで新しい コードが起動するようにしてください。（serve と Claude Code プラグインはセッションごとに 1 つのサーバーを実行するため、 この問題は発生しません。）

コマンド	説明
pyghidra-lite	stdio プロキシ（デフォルト）— バックエンドを自動起動
pyghidra-lite serve	直接 stdio サーバー（セッションごとに JVM を 1 つ起動）
pyghidra-lite serve -t streamable-http	永続的な HTTP バックエンドを手動で起動
pyghidra-lite stop	共有バックエンドを停止
pyghidra-lite doctor [--json]	環境を診断（読み取り専用。解析に失敗する場合は終了コード 1）

PYGHIDRA_LITE_NO_AUTOSTART=1 を設定すると、自動起動を無効にできます（systemd での使用に便利です）。

設定

各設定は serve フラグまたは環境変数です（MCP の env ブロックで便利です）。

変数	フラグ	デフォルト	用途
GHIDRA_INSTALL_DIR	--ghidra-dir	自動検出	Ghidra のインストール先
PYGHIDRA_LITE_PROJECT_DIR	--project-dir	下記を参照	解析キャッシュ
PYGHIDRA_LITE_RESTRICT_PATHS	--restrict-path（繰り返し指定可能）	制限なし	これらのディレクトリ以下にあるバイナリのみを読み込み（環境変数では OS のパス区切り文字を使用）
PYGHIDRA_LITE_ALLOW_WRITE	--allow-write	オフ	annotate を有効化（引き続き人による確認が必要）
PYGHIDRA_LITE_DEFAULT_PROFILE	--profile	fast	デフォルトの解析プロファイル
PYGHIDRA_LITE_TOOL_TIMEOUT	—	300 秒	JVM 呼び出しが応答しなくなってもクライアントがハングしないようにする、呼び出しごとの制限時間。0 で無効
PYGHIDRA_LITE_AUTH_TOKEN	--auth-token	なし	HTTP トランスポート用のベアラートークン（ループバック以外では必須）
PYGHIDRA_LITE_NO_AUTOSTART	—	オフ	プロキシによるバックエンドの起動を禁止
—	--evict-after / --min-loaded	30 分 / 2	アイドル状態のバイナリをメモリから退避
—	--autopurge-days	オフ	N 日間開かれていないプロジェクトを削除

マルチエージェント対応

バイナリごとに専用の Ghidra プロジェクトが作成され、次のことが可能になります。

• 異なるバイナリの並行解析
• エージェント間での解析結果の共有
• 解析状態の永続化（再起動後も保持）
• コンテンツアドレス指定ストレージ（同じバイナリなら同じ解析結果）

プロジェクトは ~/pyghidra-lite/projects/（Windows：%LOCALAPPDATA%\pyghidra-lite\projects\）に保存されます。ただし、0.8 より前の保存先 ~/.local/share/pyghidra-lite/projects/ がすでに存在する場合は、そちらが使用されます。 --project-dir または PYGHIDRA_LITE_PROJECT_DIR で保存先を変更できます。Ghidra 12 以降では、パスの要素が . で始まるプロジェクトパスは拒否されるため、従来の ~/.local ディレクトリを使用できるのは Ghidra 11.x のみです。pyghidra-lite doctor はこの問題を警告します。

リンク

• PyPI パッケージ
• AUR パッケージ
• MCP レジストリ
• 課題トラッカー
• コントリビューション
• セキュリティポリシー
• 変更履歴

ライセンス

MIT