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

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

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

🔒 Security Model

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

• Loopback binding only: binds strictly to 127.0.0.1:13370.
• Cryptographic session token: 256-bit token stored in ~/.ph4ntom_ida_bridge_token.
• Owner-only DACL: on Windows, token files are secured with protected owner-only access before writing.
• Constant-time authorization: prevents timing side-channels during token validation.
• POST body limit: capped at 5 MiB with strict UTF-8 JSON object validation.
• CORS restriction: browser CORS is permitted only from localhost origins.
• Dynamic IDAPython disabled by default: execution requires explicit IDA_BRIDGE_ALLOW_EXEC=1.
• Header imports restricted: POST /api/import-header requires pre-configured trusted root paths.

[!CAUTION]
Never expose port 13370 through a public interface, tunnel, or reverse proxy. See SECURITY.md for full hardening guidance.

📦 Components

💻 CLI Quick Start

The included CLI provides instant control over your IDA session from any terminal:

# Health & info
ph4ntom-ida ping
ph4ntom-ida info

# Functions & strings
python cli.py functions --limit 50
python cli.py strings --filter "socket|http|connect"

# Decompilation & Cross-references
python cli.py decompile 0x140001000
python cli.py xrefs 0x140001000
python cli.py callers 0x140001000

# Direct API queries
python cli.py api GET /api/function/0x140001000/ctree
python cli.py api POST /api/function/0x140001000/rename --body '{"name":"decrypt_payload"}'

# Launch IDA with bridge autostart
python cli.py launch malware_sample.bin --wait

⚡ Optional Dynamic IDAPython Execution

Dynamic execution is intentionally off by default. Enable it only on trusted environments:

PowerShell:

$env:IDA_BRIDGE_ALLOW_EXEC = "1"

Bash:

export IDA_BRIDGE_ALLOW_EXEC=1

Execute scripts inline, from file, or piped via stdin:

python cli.py exec "result['ea'] = hex(idc.here())"
python cli.py exec --file custom_scan.py
cat analyze.py | python cli.py exec -

Scripts receive full IDAPython SDK access (idc, idaapi, idautils, ida_hexrays, etc.) and a global result dictionary returned as JSON.

🤖 Standalone Multi-Backend AI Agent

No IDE? Run the built-in terminal agent with any major LLM provider:

python -m pip install -e ".[agents]"

python agent.py --backend ollama        # 🏠 Local (Ollama, private & offline)
python agent.py --backend gemini        # ☁️ Google Gemini
python agent.py --backend anthropic     # ☁️ Anthropic Claude 3.5 Sonnet
python agent.py --backend openai        # ☁️ OpenAI GPT-4o
python agent.py --backend deepseek      # ☁️ DeepSeek V3

API keys are read from standard environment variables (GEMINI_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY, DEEPSEEK_API_KEY).

🧪 Testing & Verification

The test suite covers client authentication, routing contracts, MCP registration, CORS boundaries, and IDA 9.3 SDK quirks:

python -m pip install -e ".[dev,mcp]"
python -m compileall -q agent.py cli.py core ida_plugin integrations mcp_server.py server.py swarm_worker.py tests
python -m flake8 . --select=F --exclude=.venv
python -m pytest -q
python verify_mcp.py

All 54 MCP tools and 102 REST endpoints are verified against IDA Professional 9.3. See TESTING.md for reproducibility details and regression checklists.

📄 License

Distributed under the MIT License. See LICENSE for more information.