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.

The idalib-mcp server is a supervisor process that keeps each open database in its own idalib worker subprocess. Management tools let you open binaries dynamically, switch your active context between open databases, inspect session health, and route individual tool calls to specific databases — all without restarting the server.
These tools are only present when connecting through idalib-mcp. They do not appear when using the IDA GUI plugin (ida-pro-mcp).

​
Opening and closing sessions

​
idalib_open

Open a binary in its own idalib worker process and bind it to the active MCP context.
​
input_path
string
required
Absolute path to the binary file to analyze.
​
run_auto_analysis
boolean
default:"true"
Run IDA’s automatic analysis after loading. Set to false to skip analysis and open the IDB faster when reloading a previously analyzed file.
​
session_id
string
Custom session identifier. Auto-generated (8-character UUID prefix) if omitted. Must be unique across open sessions.
If the requested binary is already open in a running IDA GUI instance with the plugin loaded, idalib_open uses that GUI instance as the backend instead of spawning a duplicate headless worker. If the GUI instance later disappears, the next routed request reopens the database headlessly. 
idalib_open(input_path, ...) → IdalibOpenResult
​
success
boolean
true on success.
​
session
IdalibSessionInfo
​
message
string
Human-readable confirmation message.
​
context_id
string
The context ID that was bound to this session.
​
error
string
Error message if the open failed.

​
idalib_close

Close a database worker and remove all context bindings pointing to it.
​
session_id
string
required
Session ID to close. Obtain from idalib_list or idalib_current.
idalib_close(session_id) → IdalibCloseResult
​
success
boolean
true if the session was found and closed.
​
message
string
Confirmation message.
​
error
string
Error message if the session was not found or could not be closed.
Closing a session terminates its worker process. Any unsaved changes to the IDB are lost. Call idalib_save before closing if you want to persist annotations.

​
Context binding

Each MCP transport connection (transport context) has an active session binding. Tools that do not pass an explicit database argument are routed to the session bound to the caller’s context.

​
idalib_switch

Rebind the active context to an existing session without reopening it.
​
session_id
string
required
Session ID to bind. The session must already be open.
idalib_switch(session_id) → IdalibSwitchResult
​
success
boolean
true on success.
​
session
IdalibSessionInfo
The session that is now bound.

​
idalib_current

Return the session currently bound to the active context. 
idalib_current() → IdalibCurrentResult
Returns the same fields as IdalibSessionInfo plus context_id. Returns { "error": "No session bound..." } if the context has no binding.

​
idalib_unbind

Remove the active context’s session binding without closing the session. 
idalib_unbind() → IdalibUnbindResult
After unbinding, tools that do not pass database will fail with “No database bound for this context” until idalib_open or idalib_switch is called again.

​
Listing sessions

​
idalib_list

List all open sessions with context-binding metadata. 
idalib_list() → IdalibListResult
​
sessions
IdalibSessionListInfo[]
​
count
number
Total number of open sessions.
​
current_context_session_id
string | null
Session ID bound to the calling context, or null if unbound.

​
Saving and health

​
idalib_save

Save the current database to disk.
​
path
string
default:""
Destination path. Defaults to the existing IDB path when empty.
​
session_id
string
Session to save. Defaults to the context-bound session.
idalib_save(...) → IdalibSaveResult
​
ok
boolean
true when the save succeeded.
​
path
string
Path where the IDB was saved.
​
error
string | null
Error message, or null on success.

​
idalib_health

Probe whether a database worker is responsive.
​
session_id
string
Session to probe. Defaults to the context-bound session.
idalib_health(...) → IdalibHealthResult
​
ready
boolean
true if the worker responded without error.
​
session
IdalibSessionInfo | null
Session information if available.
​
health
object | null
Raw health response from the worker.

​
idalib_warmup

Warm up a database worker by waiting for auto-analysis, building caches, and optionally initializing Hex-Rays. Call this after idalib_open when you want to ensure the worker is fully ready before running decompilation or search operations.
​
session_id
string
Session to warm up. Defaults to the context-bound session.
​
wait_auto_analysis
boolean
default:"true"
Wait for IDA’s auto-analysis queue to drain.
​
build_caches
boolean
default:"true"
Build core caches (string list, function index, etc.).
​
init_hexrays
boolean
default:"true"
Initialize the Hex-Rays decompiler plugin.
idalib_warmup(...) → IdalibWarmupResult
​
ready
boolean
true if warmup completed successfully.
​
warmup
object | null
Raw warmup response from the worker.

​
The database argument

Every analysis tool (e.g., decompile, xrefs_to, get_bytes) accepts an optional database argument when running through idalib-mcp. If omitted, the tool is routed to the session bound to the caller’s MCP context. database accepts any of:
  • A session ID (e.g., "binary_a")
  • A filename (e.g., "crackme.elf")
  • A full input path (e.g., "/home/user/samples/crackme.elf")
# Route to specific sessions by ID
decompile("main", database="binary_a")
xrefs_to("DllMain", database="library")

# Route by filename
get_bytes("0x1000", database="crackme.elf")
If multiple open sessions share the same filename, passing the filename as database raises an ambiguity error. Use session IDs in that case.

​
Proxy-level instance management

Two additional tools handle routing between idalib-mcp and running IDA GUI plugin instances. These are not exposed through idalib-mcp directly — they are GUI plugin routing tools.
  • list_instances — Discover running IDA GUI plugin instances on the local machine.
  • select_instance — Bind the active connection to a specific GUI instance.
If you call either tool through idalib-mcp, you will receive an error directing you to use idalib_list or idalib_switch instead.

​
Multi-session workflow

The following example opens two binaries, waits for analysis, then queries both in sequence. 
# Open the main executable
idalib_open("/samples/crackme.exe", session_id="crackme")

# Open a referenced library
idalib_open("/samples/helper.dll", session_id="helper")

# Wait for both to finish analysis
idalib_warmup(session_id="crackme")
idalib_warmup(session_id="helper")

​
Worker limits

By default, idalib-mcp allows up to 4 simultaneous worker processes. Attempting to open a fifth database raises an error. Adjust the limit with the --max-workers flag or the IDA_MCP_MAX_WORKERS environment variable. 
# Allow up to 8 concurrent workers
uv run idalib-mcp --max-workers 8 --host 127.0.0.1 --port 8745

# Unlimited workers
uv run idalib-mcp --max-workers 0 --host 127.0.0.1 --port 8745

​
Isolated contexts

By default, all transport connections share a single fallback context binding. Use --isolated-contexts to give each transport connection its own independent binding — useful when multiple agents connect to the same server and need separate active databases. 
uv run idalib-mcp --isolated-contexts --host 127.0.0.1 --port 8745
With isolated contexts enabled:
  • Each transport context must call idalib_open or idalib_switch before using database-dependent tools.
  • idalib_switch and idalib_open bind only the calling context.
  • Agents can still share a session by passing database=session_id explicitly.

Build docs developers (and LLMs) love

Get started for freeTalk to us