> [!IMPORTANT]
> `--gui` は `pyghidra-mcp` を通じて Ghidra を起動します。既に実行中の外部 Ghidra インスタンスには接続しません。

または、[Dockerコンテナ](https://ghcr.io/clearbluejar/pyghidra-mcp)：```bash
docker run -i --rm ghcr.io/clearbluejar/pyghidra-mcp -t stdio

またはpipでインストール:```bash
pip install pyghidra-mcp-cli

2. **CLI を使用する** (別のターミナルで):```bash
# 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

#### カスタムプロジェクトの作成```bash
# 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

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

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

#### .gprファイルで開く```bash
# 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モードは、次のことを行いたい場合に適しています：

- CodeBrowserでプログラムを開いたり切り替えたりする
- リスト表示で関数やアドレスに移動する
- 関数の名前を変更したりコメントを追加したりして、その変更をGhidraですぐに確認する

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

`pyghidra-mcp` はデフォルトでは `--wait-for-analysis` を必要としません。解析とMCP側のインデックス処理がバックグラウンドで継続している間に、サーバーを起動できます。

これは大規模プロジェクトにとって重要です：

- 多数のバイナリを含むプロジェクトを起動しても、サーバーの起動をブロックする必要はありません
- リクエストに対応する前に完全に解析されたプロジェクトが必要な場合は、`--wait-for-analysis` を利用できます
- 大規模な既存プロジェクトでは、解析とインデックス処理の準備状態がバイナリごとに異なることを想定してください

現在の制限事項：

- Ghidraの解析状態とMCPのインデックス状態は別々です
- Ghidraではバイナリの解析が完了していても、`search_strings` やセマンティックな `search_code` がMCP側のインデックス処理を待っている場合があります
- これは、大規模な既存プロジェクトを開くときに顕著です

実際には：

- インデックスを多用する検索機能が追いつくまでの間も、逆コンパイル、ナビゲーション、名前変更、コメントはバイナリに対して引き続き機能します
- 起動時の待ち時間が即時の検索準備よりも重要であれば、デフォルトの `--no-wait-for-analysis` を維持してください
- 起動時間よりも即時の準備が重要であれば、`--wait-for-analysis` を使用してください


## 開発

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

### セットアップ

1.  **`uv` をインストール**: `uv` がインストールされていない場合は、pip を使用してインストールできます：
    ```bash
    pip install uv
    ```
    または、公式の `uv` インストールガイドに従ってください：[https://docs.astral.sh/uv/install/](https://docs.astral.sh/uv/install/)

2.  **仮想環境を作成して依存関係をインストール**：
    ```bash
    make dev-setup
    source ./.venv/bin/activate
    ```

3.  **Ghidra環境変数を設定**：Ghidraをダウンロードしてインストールし、`GHIDRA_INSTALL_DIR` 環境変数をGhidraのインストールディレクトリに設定します。
    ```bash
    # For Linux / Mac
    export GHIDRA_INSTALL_DIR="/path/to/ghidra/"

    # For Windows PowerShell
    [System.Environment]:https://raw.githubusercontent.com/clearbluejar/pyghidra-mcp/HEAD/:SetEnvironmentVariable(%27GHIDRA_INSTALL_DIR%27,%27C:%5Cpath%5Cto%5Cghidra%27)
    ```

### テストと品質

`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` は、単一のターゲットまたはターゲットのリストを受け付けるため、コールチェーンや複数のシンボルを一度に解析する際のラウンドトリップを削減します。```jsonc
// 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"]
}

#### 読み取り / 解析ツール

- `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)`: 名前またはアドレスで関数を逆コンパイルします。単一のターゲットまたはバッチ逆コンパイル用のリストを受け入れます。リッチレスポンスフラグは、各結果にcallees、strings、および/またはxrefsを添付します。`timeout_sec` はターゲットごとに適用され、各逆コンパイル試行を独立して制限します。

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

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

- `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](https://pypi.org/p/pyghidra-mcp) として公開されており、[pip](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#install-a-package)、[pipx](https://pipx.pypa.io/)、[uv](https://docs.astral.sh/uv/)、[poetry](https://python-poetry.org/)、または任意のPythonパッケージマネージャでインストールおよび実行できます。```text
$ 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.

### OpenWeb-UIとMCPOでの使用

`pyghidra-mcp`は、[MCPO](https://github.com/open-webui/mcpo)（MCP-to-OpenAPIプロキシ）を使用して、[OpenWeb-UI](https://github.com/open-webui/open-webui)と統合できます。これにより、`pyghidra-mcp`のツールを標準的なRESTful APIを通じて公開し、Webインターフェースや他のツールからアクセスできるようになります。


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


#### `uvx`を使用する場合

`uvx`を使用して、`pyghidra-mcp`と`mcpo`を一緒に実行できます。```bash
uvx mcpo -- \
  pyghidra-mcp /bin/ls

### 標準入出力 (stdio)

stdio トランスポートは、標準入力ストリームと標準出力ストリームを通じた通信を可能にします。これは、ローカル統合やコマンドラインツールに特に役立ちます。詳細については、[仕様](https://modelcontextprotocol.io/docs/concepts/transports#built-in-transport-types) を参照してください。

#### Python```bash
pyghidra-mcp

デフォルトでは、Dockerコンテナは `streamable-http` サーバーを起動するため、イメージ名の後に `-t stdio` を含め、[インタラクティブ](https://docs.docker.com/reference/cli/docker/container/run/#interactive) stdio モードで `-i` を指定して実行してください。

### Streamable HTTP

Streamable HTTP は、HTTP POST リクエストを介した JSON RPC 上のストリーミング応答を可能にします。詳細は[仕様](https://modelcontextprotocol.io/specification/draft/basic/transports#streamable-http)を参照してください。

デフォルトでは、サーバーはクライアント接続を [http://127.0.0.1:8000/mcp](http://127.0.0.1:8000/mcp) で待ち受けます。バインドアドレスを変更するには、`--host` / `--port` または環境変数 `MCP_HOST` / `MCP_PORT` を使用します。_クライアントが接続するにはサーバーが実行されている必要があります。_

#### Python```bash
pyghidra-mcp -t streamable-http

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

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

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

## インスピレーション

このプロジェクトの実装と設計は、以下の素晴らしいプロジェクトに触発されています：

* [GhidraMCP](https://github.com/lauriewired/GhidraMCP)
* [semgrep-mcp](https://github.com/semgrep/mcp)
* [ghidrecomp](https://github.com/clearbluejar/ghidrecomp)
* [BinAssistMCP](https://github.com/jtang613/BinAssistMCP)

---

## コントリビューション、コミュニティ、そしてソースからの実行

私たちは、リバースエンジニアリングの未来はエージェント指向で、文脈に基づき、スケーラブルなものになると信じています。  
`pyghidra-mcp` は、その未来への一歩であり、完全な Ghidra プロジェクトを AI エージェントや自動化パイプラインから利用可能にします。

私たちはこのプロジェクトを積極的に開発しており、フィードバック、問題報告、コントリビューションを歓迎しています。

> [!NOTE]
> フィードバック、バグ報告、機能リクエスト、コードをお待ちしています。

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

新しいツールや統合を追加する場合の推奨ワークフローは次のとおりです：

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

これにより、コードベース全体の一貫性が保証され、リバースエンジニアリングワークフローのための堅牢でスケーラブルなツールを維持できます。

______________________________________________________________________

[PyGhidra-MCP Team](https://github.com/clearbluejar/pyghidra-mcp) によって ❤️ を込めて作られました