Ramune Ida
No description available
Ask AI about Ramune Ida
Powered by Claude Β· Grounded in docs
I know everything about Ramune Ida. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Ramune-ida
[WIP] This project is under active development. APIs and features may change without notice.
The main branch contains unstable updates. For stable versions, please use commits marked with release tags.
Headless IDA Pro MCP Server β expose IDA Pro's reverse engineering capabilities to AI agents via the Model Context Protocol.
What is this?
Ramune-ida runs IDA Pro (idalib) in headless mode and wraps it as an MCP server. AI agents like Claude, Cursor, or any MCP-compatible client can decompile functions, rename symbols, set types, and execute arbitrary IDAPython β all through structured tool calls.
Key Design Decisions
Process separation β The MCP server and IDA run in separate processes. The server is pure async Python; each IDA worker is a single-threaded subprocess communicating via dedicated fd-pair pipes (JSON line protocol). This eliminates all thread-safety issues that plague IDA SDK usage.
Plugin architecture β Tools are defined by metadata (description, parameters, tags) and handler functions. The server discovers tools at startup, dynamically generates MCP tool functions, and dispatches calls to the worker. Adding a new tool requires only a metadata file and a handler β no boilerplate registration code.
Worker is stateless β Workers are disposable command executors. All management state (task queues, crash recovery) lives in the Project layer. If a worker crashes, the project spawns a new one and reopens the IDB transparently.
Architecture
MCP Client (Claude / Cursor / ...)
β Streamable HTTP / SSE
βΌ
ββββββββββββββββββββββββββββββββββββ
β MCP Server (async Python) β
β FastMCP + Project management β
β Plugin discovery + registration β
ββββββββββββββββ¬ββββββββββββββββββββ
β fd-pair pipe (JSON lines)
βββββββΌββββββ
βΌ βΌ βΌ
Worker Worker Worker
idalib idalib idalib
(plugin handlers)
Tools
Ramune-ida provides 28 tools (21 plugin tools + 7 session tools) covering the core reverse engineering workflow:
- Session (7) β project lifecycle, database open/close, async task management
- Analysis (4) β decompile, disassemble, cross-references, binary overview
- Annotation (3) β rename symbols, read/write comments
- Data (2) β auto-detect address type, read raw bytes
- Listing (5) β enumerate functions, strings, imports, names, types (with filtering)
- Search (2) β regex search across strings/names/disasm, byte pattern search
- Types (3) β get/set types on functions/variables, declare C types (struct/enum/typedef)
- Execution (1) β run arbitrary IDAPython with stdout/stderr capture
- Undo (1) β IDA 9.0+ native undo
Low-frequency or exploratory operations are covered by execute_python, which provides full IDAPython access within the IDA environment.
Features
- Metadata-driven plugin system β tools auto-discovered at startup, dynamic MCP registration, external plugin folder support
- Framework tags β
kind:read/kind:write/kind:unsafeβ write tools auto-create undo points - Tag filtering β
--exclude-tagsto hide tools from MCP by tag, path glob, or name - Graceful cancellation β SIGUSR1 +
sys.setprofilehook β 5s watchdog β SIGKILL fallback - Crash recovery β auto-recover from IDA component files, fallback to
.i64, periodic.i64packing - Output truncation β oversized output truncated with HTTP download for full content
- File upload/download β HTTP endpoints for binary and IDB transfer
Plugins
Ramune-ida supports external plugins via <data-dir>/plugins/ (default ~/.ramune-ida/plugins/). Drop a plugin folder with metadata.py + handlers.py and restart β tools appear automatically.
See Writing Plugins for the full guide, including metadata reference, framework tags, handler contract, security model, and a complete example.
Quick Start
Requirements
- Python >= 3.10
- IDA Pro 9.0+ with idalib
- uv (package manager)
Install
git clone https://github.com/RamuneIDA/Ramune-ida.git
cd Ramune-ida
uv sync
Run
# Default: Streamable HTTP on 127.0.0.1:8000
uv run ramune-ida
# Specify host and port
uv run ramune-ida http://0.0.0.0:8745
# Use IDA's bundled Python for workers
uv run ramune-ida --worker-python /opt/ida/python3
# SSE transport (legacy MCP clients)
uv run ramune-ida sse://127.0.0.1:9000
# Stdio transport (MCP over stdin/stdout, no network listener)
uv run ramune-ida stdio://
# Local mode (see "Local mode" below)
uv run ramune-ida --local stdio://
Local Mode
By default Ramune-ida treats each project as its own workspace under
<data-dir>/projects/<project_id>/ and exposes HTTP endpoints so clients
can upload binaries / download truncated outputs. This works well in
containerised deployments but is awkward for direct local use on your
own machine.
--local switches to a simpler on-disk layout:
- All projects use the server cwd as their
work_dirβ no hidden per-project directory is created. open_databaseaccepts absolute paths or paths relative to cwd; you do not need to upload anything first.- The
POST /files/...andGET /files/...HTTP endpoints are disabled (return 404). - Truncated tool outputs are written to
<cwd>/.ramune-outputs/<project_id>/and referenced by absolute filesystem path so clients can read them directly without HTTP. close_projectnever deletes the cwd; it only wipes that project's.ramune-outputs/<project_id>/subdirectory.- Web UI (
--web) is force-disabled β the Web UI would otherwise enumerate the entire cwd.
Typical configuration for a stdio-based MCP client (Claude Desktop / Cursor / Codex CLI):
{
"mcpServers": {
"ramune-ida": {
"command": "uv",
"args": ["run", "ramune-ida", "--local", "stdio://"],
"cwd": "/path/to/your/reversing/workspace"
}
}
}
MCP Client Configuration
For Claude Desktop or Cursor, add to your MCP config:
{
"mcpServers": {
"ramune-ida": {
"type": "http",
"url": "http://127.0.0.1:8000/mcp"
}
}
}
Basic Workflow
1. open_project() β get project_id
2. open_database(project_id, "target.exe") β IDA analyzes the binary
3. decompile(project_id, "main") β decompiled C code
4. rename(project_id, addr="main", new_name="entry_main")
5. set_type(project_id, addr="0x401000", type="int foo(char *buf, int len)")
6. execute_python(project_id, code) β run any IDAPython script
7. close_database(project_id) β save and close
8. close_project(project_id) β clean up
Web UI (Experimental)
Ramune-ida includes an optional web interface for observing AI agent activity and browsing IDA database state in real time. Enable it with --web:
uv run ramune-ida --web
Features:
- IDA-style linear disassembly (IDA View) with virtual scrolling and bidirectional loading
- Decompilation with tree-sitter C syntax highlighting and line-level sync
- Hex View with byte-level selection, multi-format copy, and virtual scrolling
- Address space overview bar with per-pixel type mapping, zoom, and click-to-navigate
- Right-click context menu on all panels (Copy address, Xrefs, Go to definition)
- Keyboard shortcuts (X=Xrefs, G=Search, Esc=Back, mouse side buttons)
- Cross-reference panel with manual query mode
- Local Types browser with inline C definition expansion and nested type navigation
- Search panel (regex + byte pattern)
- Real-time AI activity stream with per-tool detail expansion
- Dockable panel layout (drag, float, merge tabs) with persistent state
- Auto-navigate to main/start on database open
See Web UI Documentation for details.
Note: The Web UI frontend was primarily written by AI (Claude) and has not undergone thorough code review.
Directory Layout
All data is stored under a single data directory (default ~/.ramune-ida, configurable via --data-dir or RAMUNE_DATA_DIR):
| Path | Description |
|---|---|
<data-dir>/projects/ | Project work directories (IDB files, outputs) |
<data-dir>/plugins/ | External plugin folder |
CLI Options
| Option | Default | Description |
|---|---|---|
url | http://127.0.0.1:8000 | Transport URL |
--worker-python | python | Python interpreter for IDA workers |
--soft-limit | 4 | Advisory threshold for concurrent workers |
--hard-limit | 8 | Maximum concurrent workers (0 = unlimited) |
--data-dir | ~/.ramune-ida | Data directory for projects and plugins (RAMUNE_DATA_DIR) |
--auto-save-interval | 300 | Seconds between auto-saves (0 = disabled) |
--output-max-length | 20000 | Truncate tool output beyond this many chars |
--exclude-tags | β | Comma-separated tags to exclude from MCP (supports ::* globs) |
--web | off | Enable Web UI on the same port (ignored under --local or stdio://) |
--local | off | Local mode: projects use cwd; disable /files endpoints and Web UI; outputs referenced by absolute path |
Building
From source
git clone https://github.com/RamuneIDA/Ramune-ida.git
cd Ramune-ida
uv sync
uv run ramune-ida
With frontend rebuild
Requires Node.js >= 18:
RAMUNE_BUILD_WEB=1 uv build
Without RAMUNE_BUILD_WEB, uv build uses the pre-built frontend assets in the repository.
Docker
Requires a pre-built ida-pro:latest base image with IDA Pro installed
The Dockerfile uses multi-stage build β Node.js builds the frontend, the final image only contains Python + IDA. Web UI is enabled by default.
docker build -t ramune-ida .
docker run -p 8000:8000 ramune-ida
| Environment Variable | Default | Description |
|---|---|---|
TRANSPORT | http://0.0.0.0:8000 | Transport URL |
SOFT_LIMIT | 4 | Advisory threshold for concurrent workers |
HARD_LIMIT | 8 | Maximum concurrent workers |
RAMUNE_DATA_DIR | /data/ramune-ida | Data directory (projects + plugins) |
License
MIT
