Skip to main content
Glama
ph4ntom-ida-bridge

ph4ntom-ida-bridge

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.

Python 3.10+ IDA Pro 9.x MCP Compatible Glama Rating REST API Release License: MIT Security Hardened

1. Live IDA Pro 9.5 Analysis β€” Disassembly, Hex-Rays C & Microcode IR (MMAT_0)

Live IDA Pro 9.5 Analysis

2. Struct Reconstruction, ARM32 Thumb Vtables & Compensated Batch Curation

Before vs After Type & Batch Curation

3. Sliced Non-Blocking Live Debugger (40ms WFNE_USEC), Multi-Instance CLI & Security Guardrails

Live Debugger, CLI & Security Architecture


              β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
              β”‚                     IDA Pro 9.0–9.5                     β”‚
              β”‚         ph4ntom_ida_bridge.py (143 REST Endpoints)      β”‚
              β”‚      127.0.0.1:13370..13389 (Bearer Token Protected)    β”‚
              β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                           β”‚ REST / JSON / SSE
          β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
          β–Ό                                β–Ό                               β–Ό
   β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”               β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”               β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
   β”‚  MCP Server   β”‚               β”‚   CLI / SDK   β”‚               β”‚   AI Agents   β”‚
   β”‚  131 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 (including 9.5). It combines a self-contained IDA plugin, a JSON REST API, a Python client, a CLI (ph4ntom-ida), 131 native MCP tools (ph4ntom-mcp), and optional standalone AI backends.

Version 6.4.0 expands MCP tool coverage to 131 annotated tools across the entire 139-endpoint REST surface, hardens security boundaries (blocking conditional-breakpoint script bypasses, gating POST /api/dbg/start behind IDA_BRIDGE_ALLOW_DBG_START=1, moving file exports/imports client-side, and protecting ~/.ph4ntom_ida_instances.json), replaces blocking execute_sync debugger waits with non-blocking sliced WFNE_SILENT polling (preventing UI freezes and dbg_pause deadlocks), fixes embedded/raw-firmware (0x0 imagebase) addressing and ARM Thumb vtables, and supports full IDA Professional 9.5 APIs (DBG_Hooks, inf_is_32bit_exactly, Hex-Rays Class Model API, decompiler timeouts, and XREF_EXACT).


⚑ 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."


Related MCP server: ida-pro-mcp-dsh

βš”οΈ 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

131 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

40 Tools: Watchpoints, Conditional BPs, Trace, Appcall, Evidence

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.5 Support

Verified & fully tested (9.0–9.5)

Broken on IDA 9+

Official


πŸ› οΈ MCP Tools Reference (131 Tools & 2 Resources)

The MCP server exposes 131 purpose-built tools across 8 reverse-engineering domains:

Category

Tools

Description

πŸ” Binary, Segments, Vtables & Multi-Instance

ping, get_binary_info, list_segments, create_segment, delete_segment, set_segment_attrs, read_bytes, read_vtable, create_vtable_struct, list_ida_instances, select_ida_instance

Binary metadata, hashes, module+RVA / SEG+0xOFFSET, segment CRUD, vtable extraction & C struct generation, multi-instance switching

🧩 Decompilation, AST & IDA 9.5 Classes

decompile, decompile_batch, analyze_function_context, get_disassembly, get_disasm_range, get_instruction, get_switch_info, get_ctree, get_microcode, get_local_variables, get_stack_vars, get_function_details, list_classes, get_class, get_decompiler_timeout, set_decompiler_timeout

Hex-Rays C pseudocode, one-shot combined context, batch decompile, arbitrary range disasm, jump tables, AST ctree JSON, Microcode IR (0–7), IDA 9.5 Class Model

πŸ•ΈοΈ Callgraphs & Xrefs

get_xrefs_to, get_xrefs_from, get_callers, get_callees, get_call_graph, get_basic_blocks, get_strings_used

Filtered & paginated cross-references (XREF_EXACT), discontinuous chunk traversal, caller trees, clean string literals

πŸ”Ž Search, Globals, Bookmarks & Exploration

list_functions, search_function, search_bytes, search_text, list_strings, list_names, get_global_vars, list_imports, list_exports, list_patches, list_function_gaps, list_bookmarks, add_bookmark, delete_bookmark, get_cursor, get_selection, wait_for_analysis

Full pagination (offset/limit), [start_ea, end_ea) range filters, globals, patches, undiscovered code gaps, bookmarks, and UI cursor/selection

🏷️ Types, Structs & Enums

list_structs, get_struct, create_struct, add_struct_member, delete_struct, apply_struct, list_enums, get_enum, create_enum, add_enum_member, delete_enum, list_types, get_type, create_type, delete_type, list_type_libraries, load_type_library

Full struct/enum/type CRUD and TIL type library management

✏️ Database Mutation & Code/Data

rename_function, set_name, comment_function, set_inline_comment, rename_variable, set_variable_type, set_function_type, make_function, delete_function, make_code, make_data, undefine, reanalyze, patch_bytes, batch_mutations, undo, redo, save_database, navigate_to

Verified renaming, lvar typing, code/data conversion, binary patching, compensating batch rollback

🐞 Live Debugger & Evidence

dbg_get_status, dbg_load_debugger, dbg_start, dbg_exit, dbg_list_processes, dbg_attach, dbg_detach, dbg_pause, dbg_set_breakpoint, dbg_set_watchpoint, dbg_list_breakpoints, dbg_delete_breakpoint, dbg_toggle_breakpoint, dbg_update_breakpoint, dbg_export_breakpoints, dbg_import_breakpoints, capture_evidence, dbg_continue, dbg_step_into, dbg_step_over, dbg_step_out, dbg_run_to, dbg_wait_event, dbg_get_registers, dbg_set_register, dbg_read_memory, dbg_write_memory, dbg_get_memory_map, dbg_refresh_memory, dbg_search_memory, dbg_list_modules, dbg_list_threads, dbg_thread_action, dbg_get_stack, dbg_configure_trace, dbg_get_trace, dbg_clear_trace, dbg_list_exceptions, dbg_configure_exception, dbg_get_events, dbg_clear_events, dbg_send_command, dbg_appcall

Non-blocking sliced debugger waits, hardware watchpoints, conditional log_and_continue breakpoints, chunk-overlap memory search, module+RVA ASLR persistence, and client-side JSON evidence capture

⚑ 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:

  • 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 & breakpoint conditions disabled by default: /api/exec, /api/dbg/cmd, /api/dbg/appcall, and conditional breakpoint scripts require explicit IDA_BRIDGE_ALLOW_EXEC=1.

  • Process spawning gated: POST /api/dbg/start requires IDA_BRIDGE_ALLOW_DBG_START=1 (or IDA_BRIDGE_ALLOW_EXEC=1).

  • Server-side file I/O restricted: HTTP GET never writes files; server-side POST imports/exports require IDA_BRIDGE_ALLOWED_IMPORT_ROOTS / IDA_BRIDGE_ALLOWED_EXPORT_ROOTS (MCP and CLI handle files client-side).

CAUTION

Never expose port 13370 through a public interface, tunnel, or reverse proxy. SeeSECURITY.md for full hardening guidance.


πŸ“¦ Components

Path

Purpose

ida_plugin/ph4ntom_ida_bridge.py

Canonical IDA plugin and REST server (139 endpoints)

api_schema.json

Machine-readable REST reference & OpenAPI schema

core/client.py

Shared authenticated HTTP client with token refresh & multi-instance discovery

cli.py

CLI, plugin installer, doctor, evidence dumper, and IDA launcher

mcp_server.py

FastMCP server (ph4ntom-mcp) exposing 131 tools and two resources

agent.py

Interactive terminal agent with 5 interchangeable LLM backends

swarm_worker.py

Structured batch-analysis worker

agent_config.json

Machine-readable integration specification for IDE agents

.agents/skills/ida-pro/

Portable IDA Pro 9.5 Agent Skill (SKILL.md + SDK/firmware/debugger references; install globally via ph4ntom-ida install-skill)

AGENT_SKILL.md

Legacy single-file CLI guide for IDE agents


πŸ’» 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 131 MCP tools and 139 REST endpoints are verified against IDA Professional 9.3–9.5. See TESTING.md for reproducibility details and regression checklists.


πŸ“„ License

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      F
      maintenance
      Enables LLM clients like Claude to interact with IDA Pro for binary analysis, decompilation, cross-references, patching, and more via 41 MCP tools, 8 resources, and 7 guided prompts.
      50
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables LLMs to perform binary analysis and reverse engineering via IDA Pro's headless idalib, providing 66 MCP tools like decompile, disasm, and xrefs without requiring the IDA GUI.
      5
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI-powered reverse engineering in IDA Pro by letting MCP clients inspect decompilation and disassembly, rename symbols, convert integers, and otherwise interact with the database through natural language.
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Deterministic, local-first MCP server for IDA Pro and IDA Home, exposing 109 strict-schema operations for reverse engineering with policy-gated mutations, evidence tracking, and broad AI-client support.
      15
      GPL 3.0