Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/mrexodia/ida-pro-mcp/llms.txt

Use this file to discover all available pages before exploring further.

idalib-mcp is a headless MCP server that uses IDA’s idalib library to analyze binaries without opening the IDA GUI. It manages a pool of worker subprocesses — one per open database — and routes MCP tool calls to the correct worker. This makes it suitable for automated pipelines, CI workflows, and multi-file analysis sessions driven by an LLM agent.

​
Activating idalib

Before using idalib-mcp, you must activate idalib globally so Python can find it. Run the activation script once with uv: 
uv run "C:\Program Files\IDA Professional 9.3\idalib\python\py-activate-idalib.py"

​
Starting the server

1

Start with an initial binary

Pass a path to a binary and the server opens it immediately as the default session:
uv run idalib-mcp --host 127.0.0.1 --port 8745 path/to/executable
2

Start without a binary

Omit the path to start an empty server. Open databases dynamically with idalib_open(...) and close them with idalib_close(session_id):
uv run idalib-mcp --host 127.0.0.1 --port 8745
3

Use stdio transport

For MCP clients that use stdio (most CLI-based agents):
uv run idalib-mcp --stdio

​
Session model

idalib-mcp keeps each open database in its own idalib worker subprocess. This means:
  • Multiple databases can be open simultaneously, each in an isolated process.
  • If the requested IDB is already open in a running GUI IDA instance, idalib-mcp uses that GUI instance instead of spawning a duplicate headless worker.
  • If the GUI instance disappears later, the next routed request reopens the database in a headless worker automatically. Unsaved GUI-only changes must be saved first if they should be visible after fallback.
Tools target either the database bound to the current MCP context, or an explicit database argument. The database parameter accepts a session ID, filename, or input path.

​
Typical workflow

idalib_open("/path/to/binary_a.exe", session_id="binary_a")
idalib_open("/path/to/library.dll", session_id="library")

decompile("main", database="binary_a")
xrefs_to("ImportantExport", database="library")
When database= is omitted, tools use the database bound to the active context.

​
Worker controls

Control how many database workers run simultaneously:
OptionDescription
--max-workers NMaximum simultaneous workers (0 = unlimited, default 4)
IDA_MCP_MAX_WORKERSEnvironment variable default for --max-workers
uv run idalib-mcp --stdio --max-workers 4

​
Isolated contexts

By default, all MCP transport sessions share a single context binding. Use --isolated-contexts to give each transport session its own independent database binding: 
uv run idalib-mcp --isolated-contexts --host 127.0.0.1 --port 8745 path/to/executable

​
Why use --isolated-contexts?

Use it when multiple agents connect to the same idalib-mcp server and you want deterministic context isolation:
  • Prevents one agent from accidentally changing another agent’s active database.
  • Keeps each transport context’s default database explicit.
  • Still allows intentional cross-session access by passing database=... or binding multiple agents to the same session ID.
When --isolated-contexts is enabled:
  • Each transport context has its own binding (Mcp-Session-Id for /mcp, session for /sse, stdio:default for stdio).
  • Unbound contexts fail fast for IDB-dependent tools unless database is provided.
  • idalib_switch(session_id) and idalib_open(...) bind the caller context only.

​
Streamable HTTP behavior

With --isolated-contexts, strict Streamable HTTP session semantics are enforced, including Mcp-Session-Id header validation.

​
Context tools

These tools manage which database is active for the current MCP context:
ToolDescription
idalib_open(input_path, ...)Open a binary in a worker and bind it to the active context
idalib_switch(session_id)Rebind the active context to an existing open session
idalib_current()Return the session bound to the active context
idalib_unbind()Remove the active context binding
idalib_list()List all sessions with is_active, is_current_context, bound_contexts, backend (worker or gui), and process IDs
The idalib feature was contributed by Willi Ballenthin.

Build docs developers (and LLMs) love

Get started for freeTalk to us