Key capabilities of this implementation include:

• Stateless Gateway: A proxy layer allows agents to interact with multiple IDA Pro instances (GUI and Headless) concurrently. The gateway automatically discovers and manages connections, allowing users to open and close databases without reconfiguring the client.

• Headless Mode: Perform analysis in the background without the IDA Pro GUI, suitable for automated workflows. Sessions can be managed directly by the AI agent.

• Relational SQL Engine: Integrates a read-only SQLite relational database populated on-demand and synchronized via IDA event hooks. Queries execute concurrently in background threads without blocking IDA's main UI thread, and an AST query layer (sqlglot) handles unsigned 64-bit memory arithmetic, comparison rewriting, and hex literals.

• WYSIWYG Disassembly: Disassembly tools (like disassemble_function and disassemble_code) return formatted text matching the IDA Pro UI, including opcode bytes, data definitions, and comments. Includes get_ida_view for viewing arbitrary memory ranges.

• Analysis & Modification Tools: Includes tools for UI navigation (jump_to_address, set_color), memory inspection (hexdump), byte patching (patch_bytes), database exporting (export_file), cross-references (get_xrefs_from, get_data_xrefs_from), and structured data creation.

• Context-Aware Assembly Patching: Powered by Keystone at the Gateway layer, the patch_assembly tool allows assembling and applying instructions directly at target addresses. It can resolve IDA symbols (function names, labels, globals) within assembly strings and evaluate basic operand math across supported architectures (x86/x64, ARM/AArch64, MIPS, PowerPC, etc.), making it convenient for quick hotpatching, stubbing out checks, or testing alternative execution paths.

• Pagination and Caching: Implements paginated resource iteration for symbol and string listing, reducing memory overhead on large binaries.

• Security Dashboard: A web-based interface for managing permissions for "unsafe" tools (e.g., Python code execution), providing control over agent capabilities.

• Unix Domain Socket (UDS) Support: In addition to TCP, the server supports UDS for secure local communication in isolated environments (Linux/macOS).

The core of this project is the Gateway Pattern. A central gateway process acts as a proxy that routes requests from the AI agent to the correct active IDA instance.

• Discovery: IDA instances (GUI or headless) register themselves by writing a metadata file to a shared directory.
• Routing: The gateway monitors this directory and manages a routing table. When a tool call arrives with a specific database_id, the gateway forwards it to the corresponding IDA process.
• Statelessness: This design decouples the agent from the backend. The agent communicates only with the gateway, and IDA instances can be opened or closed without affecting the agent's connection.

This architecture enables a multi-session analysis environment where the agent can work with multiple binaries concurrently.

The configuration file is located at ~/.idamcp.json. Here is a complete example of all available settings (showing defaults):

{
  "communication_channel": "uds",
  "registry_dir": "~/.ida_mcp_registry",
  "uds_dir": "/tmp/ida_mcp_uds",
  "max_headless_instances": 1,
  "headless_open_timeout": 600.0,
  "python_path": "/usr/bin/python3",
  "enable_all_unsafe_tools": false,
  "enabled_unsafe_tools": ["idapython_eval", "dbg_step_over"],
  "opcode_bytes": 8,
  "set_opcode_bytes": true,
  "populate_tables_on_startup": false,
  "sqlite_persistent": false,
  "disabled_tools": [],
  "proxy_host": "localhost",
  "proxy_port": 8000
}

• communication_channel: Use "uds" for secure, local-only communication (Linux/macOS) or "tcp" for networked setups. Windows environments will default to "tcp".
• max_headless_instances: Limits how many background IDA processes the MCP Client (e.g., Gemini CLI) can spawn. This limit does not apply to manually launched instances.
• headless_open_timeout: Timeout in seconds for opening a headless IDA instance. Increase this value if you're experiencing timeout errors with large binaries or on slower hardware.
• opcode_bytes: Specifies how many instruction/data bytes to display in the disassembly view (0 to disable, N to show up to N bytes).
• set_opcode_bytes: If True, the plugin will automatically configure IDA's OPCODE_BYTES setting on startup using the value of opcode_bytes.
• sqlite_persistent: If True, the Sqlite database used by sql_query will be saved to a .db file in the same directory as your IDA IDB file. This avoids re-populating tables every time you open the database.
• disabled_tools: A list of case-insensitive regular expressions. Any tool whose name matches a pattern in this list will not be registered. Use this to restrict the agent's capabilities.
• proxy_host: The hostname or IP address the Gateway Proxy binds to when running in SSE or HTTP mode. Defaults to localhost.
• proxy_port: The port the Gateway Proxy binds to when running in SSE or HTTP mode. Defaults to 8000.

You can override certain configuration settings using environment variables:

• POPULATE_TABLES_ON_STARTUP: Set to true, 1, or yes to enable table population at startup.
• SQLITE_PERSISTENT: Set to true, 1, or yes to enable persistent Sqlite storage.
• ENABLE_ALL_UNSAFE_TOOLS: Set to true to enable all unsafe tools.
• ENABLED_UNSAFE_TOOLS: A comma-separated list of specific unsafe tools to enable (e.g., idapython_eval,dbg_step_over).
• DISABLED_TOOLS: A comma-separated list of regular expressions to disable specific tools (e.g., ^dbg_.*,^patch_.*).
• PROXY_HOST: The host for the Gateway Proxy to listen on.
• PROXY_PORT: The port for the Gateway Proxy to listen on.

Some powerful tools (like arbitrary Python execution) are marked as "unsafe" by default. To manage these permissions and view active sessions:

1. Start the Security Dashboard: python3 -m frontend.security_dashboard
2. Open your browser to http://127.0.0.1:8080 (the dashboard opens automatically by default).
3. Use the interface to approve/deny tools.

The dashboard supports the following CLI arguments:

• --port <number>: Specify the port to run on (default: 8080).
• --no-browser: Disable automatic browser opening.

In case you just want to enable specific tools temporarily, you can use the environment variables, for example:

ENABLE_ALL_UNSAFE_TOOLS=true <gemini/headless/ida>
ENABLED_UNSAFE_TOOLS=idapython_eval,dbg_step_over <gemini/headless/ida>