Content
# idat-mcp
Based on [IDA Pro](https://hex-rays.com/ida-pro/), a headless MCP server exposing binary analysis capabilities through **HTTP (Streamable HTTP)**, for MCP clients like Cursor, Claude.
Underlying uses IDA 9+ **idalib** (same analysis engine as `idat` text mode).
## Requirements
- IDA Pro 9+ (with a valid license; decompilation requires Hex-Rays)
- Python 3.11+
- Linux / macOS / Windows
## Installation
Please choose one of the following installation methods based on your usage scenario, do not execute both.
### Method 1: Install as a systemd service (Linux, recommended)
Suitable for scenarios where you need to start at boot, run in the background, or provide long-term MCP services. `setup.py` will complete all installation steps and register the service, so there is no need to execute "Method 2".
Recommended for ordinary users to install as a user-level service without `sudo`:
```bash
python3 setup.py --user --ida-dir /path/to/ida
```
If you really need a system-level service, use the following command instead; do not install both user-level and system-level services:
```bash
sudo python3 setup.py --ida-dir /path/to/ida
```
Default listening on `127.0.0.1:8745`. If you need to modify, specify during the first installation or re-execution of the installer:
```bash
python3 setup.py --user --ida-dir /path/to/ida --host 0.0.0.0 --port 9000
```
The installer will automatically create `.venv`, install project dependencies and idalib Python bindings, activate idalib, and then enable and start the service. If `--ida-dir` is not specified, it will read the `IDADIR` environment variable.
Re-running the installer is safe: completed steps will be skipped, and configuration changes will only re-execute the corresponding steps.
Other installation options:
- `--dry-run`: Preview systemd unit only, do not modify the system
- `--no-start`: Install and enable the service, but do not start immediately
- `--force-reinstall`: Ignore installation status and completely reinstall dependencies, re-activate idalib
No need to manually run `server.py` after installation. User-level services can be managed with the following commands:
```bash
systemctl --user status idat-mcp
systemctl --user restart idat-mcp
systemctl --user stop idat-mcp
```
System-level services remove `--user` from the command.
### Method 2: Install command-line program only (manual run)
Suitable for development debugging, not wanting to register a systemd service, or using macOS / Windows. After completion, you need to start the server yourself. Do not run `setup.py` when choosing this method:
```bash
cd idat-mcp
python3 -m venv .venv
source .venv/bin/activate
# 1. Upgrade pip
pip install -U pip
# 2. Install current project and dependencies in editable mode
pip install -e .
# 3. Install idalib Python binding package (replace the path with your IDA installation path)
pip install /path/to/ida/idalib/python/idapro-*.whl
# 4. Activate idalib (once, replace the path with your IDA installation directory)
python /path/to/ida/idalib/python/py-activate-idalib.py -d /path/to/ida
```
### Manual startup (Method 2 only)
```bash
python server.py --ida-dir /path/to/ida
```
Common parameters:
```bash
python server.py --ida-dir /path/to/ida --host 0.0.0.0 --port 8745
python server.py -d /path/to/ida --stateless
```
Service address: `http://127.0.0.1:8745/mcp`
## MCP Client Configuration
```json
{
"mcpServers": {
"idat-mcp": {
"url": "http://127.0.0.1:8745/mcp"
}
}
}
```
## Command-line Parameters
| Parameter | Default | Description |
|-----------|---------|-------------|
| `--ida-dir` / `-d` | *(required)* | IDA installation directory |
| `--host` | `127.0.0.1` | HTTP binding address |
| `--port` | `8745` | HTTP port |
| `--max-workers` | unlimited | Maximum number of databases opened simultaneously |
| `--debug` | `false` | Output MCP tool call parameters, worker/op level, result summary, and time consumption to stderr |
| `--stateless` | `false` | Stateless HTTP mode |
| `--allowed-hosts` | *(empty)* | Remote access Host whitelist, e.g., `172.29.64.1:*` |
## Remote Access (WSL / LAN)
If you installed the service using "Method 1", re-run the installer to update the listening address:
```bash
python3 setup.py --user --ida-dir /path/to/ida --host 0.0.0.0 --port 8745
```
If you installed manually using "Method 2", specify the listening address in the startup command:
```bash
python server.py --ida-dir /path/to/ida --host 0.0.0.0 --port 8745
```
## Multi-database Parallel Analysis
**Supported.** Each database runs in an independent worker process (each loading a copy of idalib), without conflicts.
```text
MCP Client
├── worker-1 → /path/to/a.bin
├── worker-2 → /path/to/b.bin
└── worker-3 → /path/to/c.bin
```
### Usage
```python
# Open the first (automatically becomes the default database)
ida_open_database("/path/to/a.bin")
# Open the second, first still retained
ida_open_database("/path/to/b.bin")
# List opened databases and current default
ida_list_databases()
# Switch default database
ida_select_database("/path/to/a.bin")
# Subsequent analysis tools target the default database, no need to specify database
ida_list_functions(limit=10)
ida_decompile_function("main")
# Close default database
ida_close_database()
```
Rules:
- After each successful `ida_open_database`, the newly opened database automatically becomes the **default database**
- Other opened databases remain in independent workers
- When using multiple databases, switch the default database with `ida_select_database`
- All analysis tools always target the **default database**, no need to pass `database` parameter
- `ida_close_database` closes the current default database by default; after closing the default database, automatically switch to the first remaining one
## Provided MCP Tools
### Database Management
| Tool | Description |
|------|-------------|
| `ida_open_database` | Open binary file and automatically analyze |
| `ida_analyze_database` | Perform complete automatic analysis on the current default database (suitable for situations where the list only returns import tables, etc., and analysis is incomplete) |
| `ida_close_database` | Close database (default closes current default database) |
| `ida_list_databases` | List opened databases (including `is_default` field) |
| `ida_select_database` | Select default database |
| `ida_get_database_info` | Get database metadata |
| `ida_list_segments` | List memory segments |
### Function Analysis
| Tool | Description |
|------|-------------|
| `ida_list_functions` | List functions analyzed by IDA (default excludes imports/PLT) |
| `ida_get_function` | Query a single function |
| `ida_decompile_function` | Decompile (requires Hex-Rays) |
| `ida_disassemble` | Disassemble (size in bytes, supports `64` or `"0x14"`) |
| `ida_get_function_callers` | Query who called this function |
| `ida_get_function_callees` | Query which functions are called by this function |
| `ida_get_function_cfg` | Get function control flow basic blocks |
| `ida_rename_function` | Rename function |
### Cross-references and Search
| Tool | Description |
|------|-------------|
| `ida_get_xrefs_to` | Query references to a certain address |
| `ida_get_xrefs_from` | Query references from a certain address |
| `ida_get_global_variable_xrefs` | Query global symbol references (including the function where it is located) |
| `ida_search_strings` | Search for strings |
| `ida_search_bytes` | Search for byte sequences (supports `??` wildcard) |
| `ida_search_immediate` | Search for immediate values |
| `ida_list_global_names` | List global symbol names |
### Import/Export
| Tool | Description |
|------|-------------|
| `ida_list_imports` | List import tables |
| `ida_list_exports` | List exports/entry points |
| `ida_demangle` | C++ symbol demangle |
### Types and Structures
| Tool | Description |
|------|-------------|
| `ida_list_structs` | List local structure types |
| `ida_get_struct_members` | View structure members |
| `ida_get_type_at_address` | Read type at address |
| `ida_set_type_at_address` | Set C type for data/global |
| `ida_apply_function_type` | Set function prototype |
| `ida_create_struct` | Create/update structure with C declaration |
| `ida_add_struct_member` | Add member to structure |
| `ida_apply_struct_at_address` | Apply structure type to address |
| `ida_rename_local_variable` | Rename decompiled local variable (requires Hex-Rays) |
| `ida_set_local_variable_type` | Set decompiled local variable type (requires Hex-Rays) |
### Variable Analysis
| Tool | Description |
|------|-------------|
| `ida_list_local_variables` | List decompiled local variables (requires Hex-Rays) |
| `ida_get_local_variable_xrefs` | Find local variable usage points in pseudocode (requires Hex-Rays) |
### High-level Program Analysis
| Tool | Description |
|------|-------------|
| `ida_find_call_path` | Search for a path from the start function to the end function in the call graph (BFS shortest path + alternative paths, `max_depth` / `max_paths` adjustable) |
| `ida_get_backward_slice` | Perform backward slice on local variables from a sink address, returning pseudocode statements affecting the variable (requires Hex-Rays) |
| `ida_resolve_indirect_calls` | Resolve indirect calls within a function (like AArch64 `BLR`), infer possible callees, and optionally add `add_cref` to complete control flow |
| `ida_get_microcode` | Extract Hex-Rays microcode (`mblock`/`minsn`, SSA IR, block successor edges; requires Hex-Rays, suitable for OLLVM anti-obfuscation) |
| `ida_find_crypto_constants` | Scan for cryptographic magic constants like AES/MD5/SHA/ChaCha20/CRC32, optionally add `[Crypto]` comments automatically |
### Script Execution
| Tool | Description |
|------|-------------|
| `ida_exec_script` | Execute IDAPython script in the current worker; can assign `result` to return results |
### Annotations and Raw Data
| Tool | Description |
|------|-------------|
| `ida_get_bytes` | Read raw bytes |
| `ida_get_comment` | Read comments |
| `ida_set_comment` | Set comments |
## Typical Workflow
1. Call `ida_open_database` to open the first binary (automatically becomes the default database)
2. Continue `ida_open_database` to open more binaries (previous databases still retained)
3. Switch the current working database with `ida_select_database`
4. Directly call analysis tools (targeting the default database)
5. Use `ida_find_call_path` / `ida_get_backward_slice` / `ida_resolve_indirect_calls` for inter-function path and slice analysis
6. Close with `ida_close_database` after completion
## Architecture
```
MCP Client (HTTP)
│
▼
idat-mcp (FastMCP + uvicorn)
│ tools/ ← MCP tool registration (categorized by file)
│ ops/ ← IDA operation implementation (categorized by file)
│
├── worker-1 (idapro) ←→ Database A
├── worker-2 (idapro) ←→ Database B
└── worker-N ...
```
Source code layout:
| Directory | Description |
|-----------|-------------|
| `src/idat_mcp/tools/` | MCP tool definitions (`database.py`, `functions.py`, `analysis.py`, `types.py`, etc.) |
| `src/idat_mcp/ops/` | IDA low-level operations (one-to-one correspondence with tools) |
## License
MIT
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available