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

概述

pyghidra-mcp 是一个命令行模型上下文协议（MCP）服务器，它将 Ghidra（一套强大的软件逆向工程（SRE）套件）的完整分析能力带入智能代理和基于 LLM 的工具生态中。 它通过 pyghidra 和 jpype 将 Ghidra 的 ProgramAPI 和 FlatProgramAPI 桥接到 Python，然后通过模型上下文协议暴露这些功能。

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

借助 pyghidra-mcp，Ghidra 成为一个智能后端——随时准备响应上下文丰富的查询、自动化深度逆向工程任务，并集成到 AI 辅助工作流中。

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

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

[!NOTE] 这个 beta 项目正在积极开发中。我们非常期待你的反馈、错误报告、功能请求和代码。

又一个 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 及其项目作为单个长期运行的服务器保持存活，并可与 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 模型上下文协议服务器
  • 概述
  • 又一个 Ghidra MCP？
  • 设置示意图
    • 各部分如何连接
    • 选择模式
  • 目录
  • 快速开始
  • 为智能体优化
  • CLI 客户端
    • 安装
    • CLI 快速开始
  • 项目创建、管理及打开现有项目
    • 创建新项目
      • 自包含项目结构
      • 基本项目创建
      • 自定义项目创建
      • 创建多个相关项目
    • 打开现有 Ghidra 项目
      • 通过 .gpr 文件打开
    • GUI 模式
    • 启动默认值与大型项目
  • 开发
    • 设置
    • 测试与质量
  • API
    • 工具
      • 批量操作
      • 读取 / 分析工具
      • 项目操作
      • 编辑 / 变更工具
      • GUI 控制工具（仅 --gui）
  • 用法
    • 使用 Docker 映射二进制文件
    • 可流式 HTTP
      • Python
      • Docker
    • Claude Code
    • Codex
    • 标准输入/输出（stdio）
      • Python
      • Docker
    • 与 OpenWeb-UI 和 MCPO 配合使用
      • 使用 uvx
      • 使用 Docker
    • 服务器发送事件（SSE）
      • Python
      • Docker
  • 灵感来源
  • 贡献、社区及从源码运行
    • 贡献者工作流

快速开始

使用 Python 包 和 uv 启动一个持久化的可流式 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，请将 --gui 与 streamable-http 一起使用：

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

[!IMPORTANT] --gui 通过 pyghidra-mcp 启动 Ghidra。它不会附加到已在运行的外部 Ghidra 实例。