{"id":35797556,"url":"https://github.com/zboralski/ida-headless-mcp","last_synced_at":"2026-02-27T16:06:30.260Z","repository":{"id":323955264,"uuid":"1095389581","full_name":"zboralski/ida-headless-mcp","owner":"zboralski","description":"Headless IDA Pro binary analysis via Model Context Protocol","archived":false,"fork":false,"pushed_at":"2025-12-26T11:54:48.000Z","size":275,"stargazers_count":23,"open_issues_count":1,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-27T23:48:08.734Z","etag":null,"topics":["claude","claude-code","codex","disassembler","go","ida","idalib","il2cppdumper","mcp","mcp-server","python","reverse-engineering"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zboralski.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-13T01:38:56.000Z","updated_at":"2025-12-26T23:08:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zboralski/ida-headless-mcp","commit_stats":null,"previous_names":["zboralski/ida-headless-mcp"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/zboralski/ida-headless-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zboralski%2Fida-headless-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zboralski%2Fida-headless-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zboralski%2Fida-headless-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zboralski%2Fida-headless-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zboralski","download_url":"https://codeload.github.com/zboralski/ida-headless-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zboralski%2Fida-headless-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28253884,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2026-01-09T02:00:07.210Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude","claude-code","codex","disassembler","go","ida","idalib","il2cppdumper","mcp","mcp-server","python","reverse-engineering"],"created_at":"2026-01-07T10:00:54.771Z","updated_at":"2026-02-27T16:06:30.240Z","avatar_url":"https://github.com/zboralski.png","language":"Python","funding_links":[],"categories":["Security","📚 Projects (2474 total)"],"sub_categories":["Reverse Engineering","MCP Servers"],"readme":"# IDA Headless MCP Server\n\nHeadless IDA Pro binary analysis via Model Context Protocol. Go orchestrates multi-session concurrency while Python workers handle IDA operations.\n\n## Architecture\n\n```\n┌─────────────────┐\n│  MCP Client     │  Claude Desktop, Claude Code, CLI\n│  (HTTP/SSE)     │\n└────────┬────────┘\n         │ http://localhost:17300/\n         ▼\n┌─────────────────┐\n│   Go Server     │  Session registry, worker manager, watchdog\n│   (MCP Tools)   │\n└────────┬────────┘\n         │ Connect RPC over Unix socket\n         ▼\n┌─────────────────┐\n│ Python Worker   │  IDA + idalib (one per session)\n│ (per session)   │\n└─────────────────┘\n```\n\n**Key features:**\n- Multi-session concurrency via process isolation\n- 52 MCP tools for binary analysis\n- Automatic session timeouts (4 hours default, configurable)\n- Paginated results with configurable limit (default 1000)\n- [Il2CppDumper](https://github.com/Perfare/Il2CppDumper) metadata import for Unity games\n- [unflutter](https://github.com/zboralski/unflutter) metadata import for Flutter/Dart apps\n\n## Prerequisites\n\n1. **IDA Pro 9.0+ or IDA Essential 9.2+**\n\n2. **idalib**: install and activate:\n\n   ```bash\n   ./scripts/setup_idalib.sh\n   ```\n\n   See [IDA as a Library documentation](https://docs.hex-rays.com/user-guide/idalib).\n\n3. **Go 1.21+** with protoc tools:\n   ```bash\n   make install-tools\n   ```\n\n4. **Python 3.10+** with dependencies:\n   ```bash\n   pip3 install -r python/requirements.txt\n   ```\n\n5. **Optional: [Il2CppDumper](https://github.com/Perfare/Il2CppDumper)** for Unity game analysis\n\n6. **Optional: [unflutter](https://github.com/zboralski/unflutter)** for Flutter/Dart app analysis\n   ```bash\n   # Install unflutter (provides flutter_meta.json for import_flutter)\n   git clone https://github.com/zboralski/unflutter.git\n   cd unflutter \u0026\u0026 make install\n   ```\n\n## Installation\n\n```bash\ngit clone \u003crepo-url\u003e\ncd ida-headless-mcp\nmake setup\n```\n\nThis runs idalib setup, installs Python dependencies, and builds the server.\n\nFor manual setup or troubleshooting:\n\n```bash\n./scripts/setup_idalib.sh   # Setup idalib (requires IDA Pro/Essential 9.x)\nmake install-python         # Install Python dependencies\nmake build                  # Build Go server\n```\n\n## Usage\n\n### Start Server\n\n```bash\n./bin/ida-mcp-server\n```\n\nServer starts running on port 17300 (configurable via `config.json`, env, or `--port`), exposing both transports:\n\n- Streamable HTTP (recommended): `http://localhost:17300/`\n- SSE compatibility endpoint: `http://localhost:17300/sse`\n\n### Configure Claude Desktop\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"ida-headless\": {\n      \"url\": \"http://127.0.0.1:17300/\",\n      \"type\": \"http\"\n    }\n  }\n}\n```\n\nRestart Claude Desktop after editing.\n\n### Configure Claude Code\n\nCopy `.claude/settings.json` to `~/.claude/settings.json` to grant access to all IDA MCP tools.\n\n### Basic Workflow\n\n```\n1. open_binary(path=\"/path/to/binary.so\")\n   → {\"session_id\": \"abc123\", \"has_decompiler\": true}\n\n2. run_auto_analysis(session_id=\"abc123\")\n   → {\"completed\": true}\n\n3. get_entry_point(session_id=\"abc123\")\n   → {\"address\": 4198400}\n\n4. get_decompiled_func(session_id=\"abc123\", address=4198400)\n   → {pseudocode...}\n\n5. get_functions(session_id=\"abc123\")\n   → {\"functions\": [...], \"count\": 1523}\n\n6. close_binary(session_id=\"abc123\")\n   → {\"success\": true}\n```\n\n### Flutter/Dart Import\n\n```\n1. Run unflutter on the target: unflutter meta libapp.so\n2. open_binary(path=\"libapp.so\")\n3. import_flutter(session_id=\"...\", meta_json_path=\"flutter_meta.json\")\n   → {\"functions_created\": 9926, \"structs_created\": 2090,\n      \"signatures_applied\": 9926, \"comments_set\": 34172}\n4. run_auto_analysis(session_id=\"...\")\n```\n\nThe `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.\n\nUse `tools/list` via MCP to see all available tools.\n\n## Configuration\n\nCommand line flags:\n\n```bash\n./bin/ida-mcp-server \\\n  --port 17300 \\\n  --max-sessions 10 \\\n  --session-timeout 4h \\\n  --worker python/worker/server.py \\\n  --debug\n```\n\nEnvironment variables (overridden by CLI flags):\n\n```bash\nIDA_MCP_PORT=17300\nIDA_MCP_SESSION_TIMEOUT_MIN=240\nIDA_MCP_MAX_SESSIONS=10\nIDA_MCP_WORKER=/custom/worker.py\nIDA_MCP_DEBUG=1\n```\n\n## Development\n\n### Build\n\n```bash\nmake build          # Build Go server\nmake proto          # Regenerate protobuf\nmake test           # Run tests + consistency checks\nmake restart        # Kill, rebuild, restart server\nmake clean          # Clean build artifacts\n```\n\n### Testing\n\nInstall test dependencies:\n```bash\npip3 install -r requirements-test.txt\n```\n\nRun tests:\n```bash\nmake test           # All tests\npytest tests/ -v    # Python tests only\ngo test ./...       # Go tests only\n```\n\n### Interactive Testing\n\nUse MCP Inspector:\n```bash\nmake run            # Start server\nmake inspector      # Launch inspector at http://localhost:5173\n```\n\n### Project Structure\n\n```\nida-headless-mcp/\n├── cmd/ida-mcp-server/   # Go MCP server entry point\n├── internal/\n│   ├── server/           # MCP tool handlers\n│   ├── session/          # Session registry\n│   └── worker/           # Worker process manager\n├── proto/                # Protobuf definitions\n├── python/worker/        # Python worker (idalib wrapper)\n├── contrib/il2cpp/       # Il2CppDumper helpers (MIT)\n└── tests/                # Test suites\n```\n\n### Adding New Tools\n\n1. Add RPC to `proto/ida/worker/v1/ida_service.proto`\n2. Regenerate: `make proto`\n3. Implement in `python/worker/ida_wrapper.py`\n4. Add handler in `python/worker/connect_server.py`\n5. Register MCP tool in `internal/server/server.go`\n\n## Session Lifecycle\n\n1. Client calls `open_binary(path)`\n2. Go creates session in registry (UUID)\n3. Go spawns Python worker subprocess\n4. Worker creates Unix socket at `/tmp/ida-worker-{id}.sock`\n5. Worker opens IDA database with idalib\n6. Go creates Connect RPC clients over socket\n7. Subsequent tool calls proxy to worker via Connect\n8. Watchdog monitors idle time (default: 4 hours)\n9. On timeout or `close_binary`: save database, kill worker, cleanup\n10. Session metadata persists under `\u003cdatabase_directory\u003e/sessions` for automatic restoration after server restart\n\n## Troubleshooting\n\n**Worker fails to start:**\n```bash\npython3 -c \"import idapro; print('OK')\"\n```\nIf this fails, run `./scripts/setup_idalib.sh`\n\n**Socket timeout:**\nCheck Python worker logs. Worker may have crashed during init.\n\n**Port already in use:**\n```bash\nlsof -ti:17300 | xargs kill\n# or use a different port\n./bin/ida-mcp-server --port 17301\n```\n\n**Session not found:**\nSession may have timed out. Use `list_sessions` to check active sessions.\n\n## License\n\nMIT\n\n## Related Projects\n\n**MCP Servers:**\n- [LaurieWired/GhidraMCP](https://github.com/LaurieWired/GhidraMCP)\n- [mrexodia/ida-pro-mcp](https://github.com/mrexodia/ida-pro-mcp)\n- [cnitlrt/headless-ida-mcp-server](https://github.com/cnitlrt/headless-ida-mcp-server)\n\n**Metadata Dumpers:**\n- [Perfare/Il2CppDumper](https://github.com/Perfare/Il2CppDumper) (used by `import_il2cpp`)\n- [zboralski/unflutter](https://github.com/zboralski/unflutter) (used by `import_flutter`)\n\n## References\n\n- [MCP Specification](https://spec.modelcontextprotocol.io/)\n- [Connect RPC](https://connectrpc.com/)\n- [IDA Pro idalib](https://hex-rays.com/products/ida/support/idapython_docs/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzboralski%2Fida-headless-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzboralski%2Fida-headless-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzboralski%2Fida-headless-mcp/lists"}