ph4ntom IDA Bridge 🌉

Autonomous AI & MCP Control Layer for IDA Pro 9.x
Turn IDA Pro into an agentic reverse-engineering powerhouse. Connect Claude Desktop, Cursor, Antigravity, or custom LLM agents via Model Context Protocol (MCP) or high-performance REST API.

---

              ┌─────────────────────────────────────────────────────────┐
              │                       IDA Pro 9.x                       │
              │         ph4ntom_ida_bridge.py (102 REST Endpoints)      │
              │         127.0.0.1:13370 (Bearer Token Protected)        │
              └────────────────────────────┬────────────────────────────┘
                                           │ REST / JSON / SSE
          ┌────────────────────────────────┼───────────────────────────────┐
          ▼                                ▼                               ▼
   ┌───────────────┐               ┌───────────────┐               ┌───────────────┐
   │  MCP Server   │               │   CLI / SDK   │               │   AI Agents   │
   │  54 Tools     │               │  `ph4ntom-ida`│               │  Multi-LLM    │
   │  Claude       │               │  Automation   │               │  Gemini       │
   │  Cursor       │               │  Headless     │               │  Ollama       │
   │  Antigravity  │               │  Testing      │               │  Claude / GPT │
   └───────────────┘               └───────────────┘               └───────────────┘

ph4ntom IDA Bridge is a localhost-only control layer for IDA Pro 9.x. It combines a self-contained IDA plugin, a JSON REST API, a Python client, a CLI, 54 native MCP tools, and optional standalone AI backends.

Version 6.2.0 brings full IDA 9.3 compatibility, atomic database mutations, constant-time token authentication, SSE cursor tracking, and complete test suite coverage.

---

⚡ Quickstart: Claude Desktop & Cursor (1-Click MCP Setup)

Connect Claude Desktop, Cursor, or any MCP client to your running IDA Pro instance in 60 seconds:

1. Clone & Install

git clone https://github.com/ph4ntom-rev/ph4ntom-ida-bridge.git
cd ph4ntom-ida-bridge
python -m pip install -e ".[mcp]"

2. Install Plugin into IDA Pro

python cli.py install-plugin --ida-dir "C:\Program Files\IDA Professional 9.0"

(Or copy ida_plugin/ph4ntom_ida_bridge.py and api_schema.json directly into your IDA plugins/ directory).

3. Add to your MCP Config

🟣 Claude Desktop

Edit %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "ida-bridge": {
      "command": "python",
      "args": [
        "C:/path/to/ph4ntom-ida-bridge/mcp_server.py"
      ]
    }
  }
}

💻 Cursor / Windsurf

Add to .cursor/mcp.json or Cursor Settings → MCP:

{
  "mcpServers": {
    "ida-bridge": {
      "command": "python",
      "args": ["-m", "mcp_server"],
      "cwd": "C:/path/to/ph4ntom-ida-bridge"
    }
  }
}

Start IDA Pro, press Ctrl+Shift+A to toggle the server, and prompt your AI assistant:

"Inspect the function at 0x140001000. Trace cross-references, analyze microcode, decompile to C pseudocode, and rename obfuscated variables to meaningful names."

---

⚔️ Comparison with Alternatives

Feature	ph4ntom IDA Bridge	Gepetto / IDAGPT	Hex-Rays Copilot
Architecture	Bi-directional MCP + REST + CLI	Single prompt-wrapper	Proprietary UI plugin
Tool Count	54 Granular MCP Tools	1 (Decompile prompt)	Fixed prompt actions
AST & Control Flow	Full ctree AST + Microcode IR (0-7)	Pseudocode text only	Pseudocode text only
Safe Mutations	Atomic batch mutations with rollback	Comment insertion only	Suggestions in UI
Live Debugger	Registers, Stack, Memory, Breakpoints	No	No
Dynamic Execution	On-the-fly IDAPython execution engine	No	No
Supported LLMs	Any MCP Client / Claude / GPT / Gemini / Ollama	OpenAI API only	Proprietary cloud
Security & Auth	Localhost-only, 256-bit token, Owner DACL	Exposed plain API key	Proprietary
IDA Pro 9.3 Support	Verified & fully tested	Broken on IDA 9+	Official

---

🛠️ MCP Tools Reference (54 Tools & 2 Resources)

The MCP server exposes 54 purpose-built tools across 7 reverse-engineering domains:

Category	Tools	Description
🔍 Binary & Segments	ping, get_binary_info, list_segments, read_bytes, read_vtable	Binary metadata, bitness, permissions, vtable extraction
🧩 Decompilation & AST	decompile, get_disassembly, get_ctree, get_microcode, get_local_variables, get_function_details	Hex-Rays C pseudocode, AST ctree JSON, Microcode IR (0=PREOPT to 7=LVARS), prototype info
🕸️ Callgraphs & Xrefs	get_xrefs_to, get_xrefs_from, get_callers, get_callees, get_call_graph, get_basic_blocks, get_strings_used	Cross-references, recursive caller trees, basic block control flow
🔎 Search & Exploration	search_function, search_bytes, search_text, list_strings, list_names, list_imports, list_exports	Wildcard byte search (??), imported DLL functions, exports, string filtering
🏷️ Types & Structs	list_structs, get_struct, list_enums, list_types, get_type, create_type, create_struct	C declaration parsing, structure definitions, enum member inspection
✏️ Database Mutation	rename_function, comment_function, set_inline_comment, rename_variable, set_variable_type, set_function_type, patch_bytes, batch_mutations, undo, redo, save_database, navigate_to	Verified renaming, local variable typing, binary patching, atomic rollback
🐞 Live Debugger	dbg_start, dbg_set_breakpoint, dbg_continue, dbg_step_into, dbg_step_over, dbg_get_registers, dbg_read_memory, dbg_get_stack	Process execution control, hardware breakpoints, live register and memory dump
⚡ Dynamic IDAPython	execute_idapython	Real-time IDAPython execution with structured result capture
📦 MCP Resources	ida://info, ida://schema	Real-time binary metadata and complete OpenAPI schema

---

🔒 Security Model

The bridge runs inside IDA Pro, granting powerful capabilities. Version 6 implements defense-in-depth defaults: