Pyghidra Mcp

PyGhidra-MCP - Ghidra 模型上下文协议服务

概述

pyghidra-mcp 是一款命令行模型上下文协议（MCP）服务，将功能强大的 Ghidra——一套稳健的软件逆向工程（SRE）套件——的完整分析能力带入智能 Agent 和基于大模型的工具领域。 它通过 pyghidra 和 jpype 将 Ghidra 的 ProgramAPI 和 FlatProgramAPI 接入 Python，然后通过模型上下文协议公开这些功能。

MCP 是一种统一接口，允许语言模型、开发工具（如 VS Code）和自主 Agent 访问结构化上下文、调用工具并智能协作。可以将 MCP 看作强大分析工具与大模型生态系统之间的桥梁。

借助 pyghidra-mcp，Ghidra 将成为智能后端，可响应包含丰富上下文的查询、自动执行深度逆向工程任务，并集成到 AI 辅助工作流中。

pyghidra-mcp 现在支持两种运行模式：

• headless 模式，用于命令行驱动的分析和自动化
• --gui 模式，通过 pyghidra-mcp 启动 Ghidra，并与运行中的 GUI 共享实时程序状态

说明

此 Beta 项目正在积极开发中。欢迎反馈、提交错误报告、提出功能请求和贡献代码。

又一个 Ghidra MCP？

没错，原版 ghidra-mcp 非常出色。但 pyghidra-mcp 采取了不同的方式：

• 🐍 无头优先，支持 GUI – 完全通过 CLI 运行以简化自动化；需要实时 GUI 导航和编辑时，也可以使用 --gui 启动 Ghidra。
• 🔁 专为自动化打造 – 非常适合与大模型、CI 流水线以及需要可重复行为的工具集成。
• ✅ 适合 CI/CD – 为客户端和服务端会话提供稳健的单元测试和集成测试。
• 🚀 快速启动 – 异步启动让服务可在二进制文件仍于后台分析时开始处理请求。支持快速命令行启动，且只需极少配置。
• 📦 项目级分析 – 支持对 Ghidra 项目中的所有二进制文件进行并发逆向工程
• 🤖 为 Agent 做好准备 – 专为智能 Agent 驱动的工作流和大规模逆向工程自动化打造。
• 🔍 语义代码搜索 – 使用向量嵌入（通过 ChromaDB），可在反编译函数、注释和符号中快速模糊查找，非常适合探索伪 C 代码和 Agent 驱动的分类分析。

此项目提供以 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 及其项目作为一个长期运行的服务保持活动状态，并同时适用于 MCP 宿主和 CLI 客户端。
• GUI 模式：pyghidra-mcp 会启动 Ghidra、打开项目，并提供额外工具，在同一个 JVM 中控制 CodeBrowser。
• CLI 客户端：pyghidra-mcp-cli 是一个 HTTP 客户端。先启动 streamable-http 服务，然后针对该运行中的服务执行终端命令。
• stdio：仅在 MCP 宿主无法连接 HTTP 端点时使用此模式。

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 模型上下文协议服务
  • 概述
  • 又一个 Ghidra MCP？
  • 设置示意图
    • 各部分如何连接
    • 选择模式
  • 目录
  • 开始使用
  • 为 Agent 优化
  • 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

针对 Agent 优化

pyghidra-mcp 有意保持 MCP 接口简洁，让 Agent 客户端在发现工具和选择参数时消耗更少的令牌。

• 简短的工具描述：MCP 工具文档字符串保持精简，使 MCPServer 工具架构保持小巧，降低发送给模型的成本。
• 上下文管理：工具默认返回重点明确的结构化数据，而不是倾倒整个程序的上下文。反编译、符号搜索和交叉引用结果经过调整，旨在支持迭代分析，而非一次性返回大量内容。
• 仅在相关时提供 GUI 工具：只有在使用 --gui 启动服务时，才会提供 open_program_in_gui、list_open_programs、set_current_program 和 goto 等仅限 GUI 的控件。
• CLI 为可选项：如果 MCP 不是你偏好的接口，pyghidra-mcp-cli 可通过 HTTP 提供直接的命令行客户端，并为常见的编辑和分析工作流提供分组命令。

这样一来，默认服务既适用于大模型 Agent、IDE 集成和自动化，也不会暴露不必要的工具接口或仅限 GUI 的控件，从而适用于无头会话。

CLI 客户端

如需更具交互性的命令行体验，可以使用独立的 pyghidra-mcp-cli 包。它提供了一个易用的界面，用于与正在运行的 pyghidra-mcp 服务交互。

安装

使用 uv 安装 CLI 客户端（推荐）：

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 中完成分析，但 search_strings 或语义 search_code 仍在等待 MCP 侧索引
• 打开较大的现有项目时，这种情况会更加明显

实际使用中：

• 当依赖索引的搜索功能仍在处理中时，某个二进制文件的反编译、导航、重命名和注释功能仍可能正常使用
• 如果启动延迟比立即具备搜索能力更重要，请保留默认设置 --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、单元测试和一项轻量级集成冒烟测试
• GitHub Actions：完整的 Linux 无头集成测试覆盖、通过 Xvfb 运行的 Linux GUI 测试、CLI 覆盖，以及当前 macOS 冒烟测试
• 定期运行的 CI：旧版 macOS / Ghidra 兼容性覆盖
• 本地／手动：更复杂的特定环境 GUI 调试和发布前检查

API

工具

使大模型能够执行操作、进行确定性计算并与外部服务交互。

批量操作

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)：列出指定二进制文件导出的所有函数和符号（查询支持正则表达式）。

• list_imports(binary_name: str, query: str = ".*", offset: int = 0, limit: int = 25)：列出指定二进制文件导入的所有函数和符号（查询支持正则表达式）。

• read_bytes(binary_name: str, address: str, size: int = 32)：读取指定地址处的原始内存字节。十六进制地址可以包含或省略 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）

只有在使用 --gui 启动 pyghidra-mcp 时，才能使用这些工具。它们控制 GUI 的显示内容，而不会直接修改项目数据：

• list_open_programs()：列出当前在 Ghidra GUI 中打开的程序。
• open_program_in_gui(binary_name: str, new_window: bool = True)：在 CodeBrowser 中打开项目二进制文件。默认会打开新的 CodeBrowser 窗口。将 new_window=false 设置为在可能时复用可见的 CodeBrowser。
• set_current_program(binary_name: str)：将已打开的程序设为主 GUI 工具上下文中的活动／当前程序。
• goto(binary_name: str, target: str, target_type: str)：在 Ghidra GUI 中导航到某个地址或函数。target_type 必须是 address 或 function。

用法

此 Python 软件包以 pyghidra-mcp 发布到 PyPI，可使用 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 进程和项目持续供 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 中显示的名称。

标准输入/输出（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，并使用 -i 进入交互式 stdio 模式。

与 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

服务器发送事件（SSE）

警告

MCP 社区认为这是一种用于向后兼容的旧式传输协议。建议改用 Streamable HTTP。

SSE 传输使用服务器发送事件（Server-Sent 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

贡献、社区与从源代码运行

我们相信，逆向工程的未来将由 Agent 驱动、具备上下文感知能力且可扩展。
pyghidra-mcp 是迈向这一未来的一步，让 AI Agent 和自动化流水线能够访问完整的 Ghidra 项目。

我们正在积极开发本项目，欢迎反馈、问题报告和贡献。

说明

我们期待收到你的反馈、错误报告、功能请求和代码贡献。

贡献者工作流

如果你要添加新工具或集成，建议按以下工作流操作：

• 使用 feature/ 前缀为分支命名，以表示新增功能。
• 按照 pyghidra/tools/ 中现有工具的风格和结构添加工具。
• 编写集成测试，使用 StdioClient 实例测试你的工具，并将测试放在 tests/integration/ 中。
• 在 tests/integration/test_concurrent_streamable_client.py 中添加对你工具的调用，以扩展并发测试。
• 运行 make test 和 make format，确保所有测试通过且符合 lint 规则。

这有助于保持整个代码库的一致性，并帮助我们为逆向工程工作流维护可靠、可扩展的工具。

由 PyGhidra-MCP Team 倾情打造 ❤️