IDA Headless MCP Server

1# IDA Headless MCP Server
2 
3Headless IDA Pro binary analysis via Model Context Protocol. Go orchestrates multi-session concurrency while Python workers handle IDA operations.
4 
5## Architecture
6 
7```
8┌─────────────────┐
9│  MCP Client     │  Claude Desktop, Claude Code, CLI
10│  (HTTP/SSE)     │
11└────────┬────────┘
12         │ http://localhost:17300/
13         ▼
14┌─────────────────┐
15│   Go Server     │  Session registry, worker manager, watchdog
16│   (MCP Tools)   │
17└────────┬────────┘
18         │ Connect RPC over Unix socket
19         ▼
20┌─────────────────┐
21│ Python Worker   │  IDA + idalib (one per session)
22│ (per session)   │
23└─────────────────┘
24```
25 
26**Key features:**
27- Multi-session concurrency via process isolation
28- 52 MCP tools for binary analysis
29- Automatic session timeouts (4 hours default, configurable)
30- Paginated results with configurable limit (default 1000)
31- [Il2CppDumper](https://github.com/Perfare/Il2CppDumper) metadata import for Unity games
32- [unflutter](https://github.com/zboralski/unflutter) metadata import for Flutter/Dart apps
33 
34## Prerequisites
35 
361. **IDA Pro 9.0+ or IDA Essential 9.2+**
37 
382. **idalib**: install and activate:
39 
40   ```bash
41   ./scripts/setup_idalib.sh
42   ```
43 
44   See [IDA as a Library documentation](https://docs.hex-rays.com/user-guide/idalib).
45 
463. **Go 1.21+** with protoc tools:
47   ```bash
48   make install-tools
49   ```
50 
514. **Python 3.10+** with dependencies:
52   ```bash
53   pip3 install -r python/requirements.txt
54   ```
55 
565. **Optional: [Il2CppDumper](https://github.com/Perfare/Il2CppDumper)** for Unity game analysis
57 
586. **Optional: [unflutter](https://github.com/zboralski/unflutter)** for Flutter/Dart app analysis
59   ```bash
60   # Install unflutter (provides flutter_meta.json for import_flutter)
61   git clone https://github.com/zboralski/unflutter.git
62   cd unflutter && make install
63   ```
64 
65## Installation
66 
67```bash
68git clone <repo-url>
69cd ida-headless-mcp
70make setup
71```
72 
73This runs idalib setup, installs Python dependencies, and builds the server.
74 
75For manual setup or troubleshooting:
76 
77```bash
78./scripts/setup_idalib.sh   # Setup idalib (requires IDA Pro/Essential 9.x)
79make install-python         # Install Python dependencies
80make build                  # Build Go server
81```
82 
83## Usage
84 
85### Start Server
86 
87```bash
88./bin/ida-mcp-server
89```
90 
91Server starts running on port 17300 (configurable via `config.json`, env, or `--port`), exposing both transports:
92 
93- Streamable HTTP (recommended): `http://localhost:17300/`
94- SSE compatibility endpoint: `http://localhost:17300/sse`
95 
96### Configure Claude Desktop
97 
98Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
99 
100```json
101{
102  "mcpServers": {
103    "ida-headless": {
104      "url": "http://127.0.0.1:17300/",
105      "type": "http"
106    }
107  }
108}
109```
110 
111Restart Claude Desktop after editing.
112 
113### Configure Claude Code
114 
115Copy `.claude/settings.json` to `~/.claude/settings.json` to grant access to all IDA MCP tools.
116 
117### Basic Workflow
118 
119```
1201. open_binary(path="/path/to/binary.so")
121   → {"session_id": "abc123", "has_decompiler": true}
122 
1232. run_auto_analysis(session_id="abc123")
124   → {"completed": true}
125 
1263. get_entry_point(session_id="abc123")
127   → {"address": 4198400}
128 
1294. get_decompiled_func(session_id="abc123", address=4198400)
130   → {pseudocode...}
131 
1325. get_functions(session_id="abc123")
133   → {"functions": [...], "count": 1523}
134 
1356. close_binary(session_id="abc123")
136   → {"success": true}
137```
138 
139### Flutter/Dart Import
140 
141```
1421. Run unflutter on the target: unflutter meta libapp.so
1432. open_binary(path="libapp.so")
1443. import_flutter(session_id="...", meta_json_path="flutter_meta.json")
145   → {"functions_created": 9926, "structs_created": 2090,
146      "signatures_applied": 9926, "comments_set": 34172}
1474. run_auto_analysis(session_id="...")
148```
149 
150The `import_flutter` tool reads structured JSON metadata from unflutter. It creates Dart class structs, function definitions with typed signatures, and annotates THR/PP/string reference comments in a single pass.
151 
152Use `tools/list` via MCP to see all available tools.
153 
154## Configuration
155 
156Command line flags:
157 
158```bash
159./bin/ida-mcp-server \
160  --port 17300 \
161  --max-sessions 10 \
162  --session-timeout 4h \
163  --worker python/worker/server.py \
164  --debug
165```
166 
167Environment variables (overridden by CLI flags):
168 
169```bash
170IDA_MCP_PORT=17300
171IDA_MCP_SESSION_TIMEOUT_MIN=240
172IDA_MCP_MAX_SESSIONS=10
173IDA_MCP_WORKER=/custom/worker.py
174IDA_MCP_DEBUG=1
175```
176 
177## Development
178 
179### Build
180 
181```bash
182make build          # Build Go server
183make proto          # Regenerate protobuf
184make test           # Run tests + consistency checks
185make restart        # Kill, rebuild, restart server
186make clean          # Clean build artifacts
187```
188 
189### Testing
190 
191Install test dependencies:
192```bash
193pip3 install -r requirements-test.txt
194```
195 
196Run tests:
197```bash
198make test           # All tests
199pytest tests/ -v    # Python tests only
200go test ./...       # Go tests only
201```
202 
203### Interactive Testing
204 
205Use MCP Inspector:
206```bash
207make run            # Start server
208make inspector      # Launch inspector at http://localhost:5173
209```
210 
211### Project Structure
212 
213```
214ida-headless-mcp/
215├── cmd/ida-mcp-server/   # Go MCP server entry point
216├── internal/
217│   ├── server/           # MCP tool handlers
218│   ├── session/          # Session registry
219│   └── worker/           # Worker process manager
220├── proto/                # Protobuf definitions
221├── python/worker/        # Python worker (idalib wrapper)
222├── contrib/il2cpp/       # Il2CppDumper helpers (MIT)
223└── tests/                # Test suites
224```
225 
226### Adding New Tools
227 
2281. Add RPC to `proto/ida/worker/v1/ida_service.proto`
2292. Regenerate: `make proto`
2303. Implement in `python/worker/ida_wrapper.py`
2314. Add handler in `python/worker/connect_server.py`
2325. Register MCP tool in `internal/server/server.go`
233 
234## Session Lifecycle
235 
2361. Client calls `open_binary(path)`
2372. Go creates session in registry (UUID)
2383. Go spawns Python worker subprocess
2394. Worker creates Unix socket at `/tmp/ida-worker-{id}.sock`
2405. Worker opens IDA database with idalib
2416. Go creates Connect RPC clients over socket
2427. Subsequent tool calls proxy to worker via Connect
2438. Watchdog monitors idle time (default: 4 hours)
2449. On timeout or `close_binary`: save database, kill worker, cleanup
24510. Session metadata persists under `<database_directory>/sessions` for automatic restoration after server restart
246 
247## Troubleshooting
248 
249**Worker fails to start:**
250```bash
251python3 -c "import idapro; print('OK')"
252```
253If this fails, run `./scripts/setup_idalib.sh`
254 
255**Socket timeout:**
256Check Python worker logs. Worker may have crashed during init.
257 
258**Port already in use:**
259```bash
260lsof -ti:17300 | xargs kill
261# or use a different port
262./bin/ida-mcp-server --port 17301
263```
264 
265**Session not found:**
266Session may have timed out. Use `list_sessions` to check active sessions.
267 
268## License
269 
270MIT
271 
272## Related Projects
273 
274**MCP Servers:**
275- [LaurieWired/GhidraMCP](https://github.com/LaurieWired/GhidraMCP)
276- [mrexodia/ida-pro-mcp](https://github.com/mrexodia/ida-pro-mcp)
277- [cnitlrt/headless-ida-mcp-server](https://github.com/cnitlrt/headless-ida-mcp-server)
278 
279**Metadata Dumpers:**
280- [Perfare/Il2CppDumper](https://github.com/Perfare/Il2CppDumper) (used by `import_il2cpp`)
281- [zboralski/unflutter](https://github.com/zboralski/unflutter) (used by `import_flutter`)
282 
283## References
284 
285- [MCP Specification](https://spec.modelcontextprotocol.io/)
286- [Connect RPC](https://connectrpc.com/)
287- [IDA Pro idalib](https://hex-rays.com/products/ida/support/idapython_docs/)
288