idalib MCP Headless

Fresh headless MCP supervisor for IDA Pro 9.x through idalib.

This project keeps the IDA-facing tool surface compatible with mrexodia/ida-pro-mcp by using that package at runtime, then adds a thin supervisor layer for:

• multiple independent worker processes, one per open database/debug session;
• command-line IDA installation selection with --ida-home;
• a simple browser UI for listing and closing instances;
• MCP management tools such as idalib_open, idalib_list, and idalib_close.

Install

Use a project virtual environment with a Python supported by IDA/idapro and the upstream MCP package.

cd D:\Projects\idalib-mcp
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .

After the project is published, installation can use the GitHub archive directly:

pip install https://github.com/nyaoouo/idalib-mcp/archive/refs/heads/main.zip

If the idapro Python package is not already available, install it from your IDA installation:

pip install D:\tools\IDA_PRO_9.1\idalib\python

--ida-home configures idalib for the worker process without rewriting your normal %APPDATA%\Hex-Rays\IDA Pro\ida-config.json.

MCP Client Setup

Print generic MCP client snippets:

idalib-mcp-headless --config --ida-home D:\tools\IDA_PRO_9.1

List supported client targets:

idalib-mcp-headless --list-clients

Install project-level MCP config for a supported client:

idalib-mcp-headless --install cursor --scope project --ida-home D:\tools\IDA_PRO_9.1

Install a stdio config that lets the MCP client launch the headless server itself:

idalib-mcp-headless --install claude --transport stdio --scope global --ida-home D:\tools\IDA_PRO_9.1

In stdio mode the MCP protocol still uses stdin/stdout, and the instance manager is started as a local HTTP sidecar. The server writes the web UI URL to stderr, for example:

Instance UI: http://127.0.0.1:8745/instances

If the configured port is already in use, stdio mode retries with an ephemeral port and prints the actual URL.

Install an HTTP config when you run the server separately:

idalib-mcp-headless --install vscode --transport streamable-http --scope project --host 127.0.0.1 --port 8745

Remove config entries with --uninstall, for example:

idalib-mcp-headless --uninstall cursor --scope project

This project is headless, so the installer only updates MCP client configuration. There is no IDA GUI plugin to install.

Run

idalib-mcp-headless --ida-home D:\tools\IDA_PRO_9.1 --host 127.0.0.1 --port 8745 --max-workers 4

Open the instance manager at:

http://127.0.0.1:8745/instances

Connect MCP clients to:

http://127.0.0.1:8745/mcp

Debugger tools are inherited from the upstream package and are hidden behind the dbg extension. Start the server with --unsafe, then connect to:

http://127.0.0.1:8745/mcp?ext=dbg

Each idalib_open call creates or reuses a distinct worker process. Normal upstream tools receive an optional database argument at the supervisor layer so calls can target a specific session by session id, filename, or path.

Useful Commands

Open a database through MCP:

{"name":"idalib_open","arguments":{"input_path":"C:\\path\\to\\sample.exe","session_id":"sample-a"}}

List instances through MCP:

{"name":"idalib_list","arguments":{}}

Close an instance through MCP:

{"name":"idalib_close","arguments":{"session_id":"sample-a"}}

The browser UI uses the same supervisor session table and calls the close operation server-side. When closing an instance from the browser UI, choose whether to save the IDB before the worker is stopped.

Validation

Run the dependency-free local checks:

python -m unittest discover -s tests -p "test*.py"
python -m py_compile src\idalib_mcp\config.py src\idalib_mcp\installer.py src\idalib_mcp\worker.py src\idalib_mcp\server.py

For an end-to-end IDA smoke test, install the dependencies in a virtual environment and start the server with the --ida-home path shown above.