# BinAssistMCP

> Comprehensive Model Context Protocol (MCP) server for Binary Ninja with AI-powered reverse engineering capabilities

## Summary

BinAssistMCP is a powerful bridge between Binary Ninja and Large Language Models (LLMs) like Claude, providing comprehensive reverse engineering tools through the Model Context Protocol (MCP). It enables AI-assisted binary analysis by exposing Binary Ninja's advanced capabilities through Server-Sent Events (SSE) and Streamable HTTP transports.

### Key Features

- **MCP 2025-11-25 Compliant**: Full support for tool annotations, resources, and prompts
- **Dual Transport Support**: SSE (Server-Sent Events) and Streamable HTTP transports
- **45 Consolidated Tools**: Streamlined Binary Ninja API wrapper with unified tool design
- **8 MCP Resources**: Browsable, cacheable binary metadata
- **7 Guided Prompts**: Pre-built workflows for common reverse engineering tasks
- **Multi-Binary Sessions**: Concurrent analysis of multiple binaries with intelligent context management
- **Context-Rich Code Output**: Function signatures and Binary Ninja comments are embedded in code results
- **Analysis-Safe Queries**: Code retrieval uses already-loaded IL and never forces global reanalysis
- **Session-Independent Discovery**: Direct tool calls discover open Binary Ninja views without requiring a prior listing call
- **Nonblocking Binary Opens**: Large binaries and `.bndb` databases open asynchronously with pollable operation status
- **Thread-Safe**: RLock-based synchronization for concurrent access
- **Auto-Integration**: Seamless Binary Ninja plugin with automatic startup capabilities

### Use Cases

- **AI-Assisted Reverse Engineering**: Leverage LLMs for intelligent code analysis and documentation
- **Protocol Analysis**: Trace network data flows and reconstruct protocol structures
- **Vulnerability Research**: Systematic security audits with guided workflows
- **Automated Binary Analysis**: Script complex analysis workflows with natural language
- **Code Understanding**: Generate comprehensive documentation and explanations

---

## Architecture

```
src/binassist_mcp/
├── server.py        # FastMCP server - SSE/Streamable HTTP transport, tool registration
├── tools.py         # Binary Ninja API wrapper - 45 MCP tools
├── plugin.py        # Binary Ninja plugin integration
├── context.py       # Thread-safe multi-binary session management
├── config.py        # Pydantic configuration with Binary Ninja settings
├── prompts.py       # 7 guided workflow prompts
├── resources.py     # 8 MCP resource definitions
├── cache.py         # Cache primitives (not currently connected to MCP tools)
├── tasks.py         # Task lifecycle support (tool dispatch is not yet implemented)
├── logging.py       # Binary Ninja logging integration
└── utils.py         # Utility functions

__init__.py          # Plugin entry point (root level)
```

---

## Tools (45 Total)

BinAssistMCP provides 45 tools organized into functional categories. Tools include MCP annotations (`readOnlyHint`, `idempotentHint`) to help clients make informed decisions.

### Binary Management
| Tool | Description |
|------|-------------|
| `list_binaries` | Synchronize with Binary Ninja and list all loaded binary files |
| `get_binary_info` | Check analysis status and metadata |
| `get_binary_status` | Poll a queued open by operation ID, path, or name and report analysis progress |
| `open_binary` | Queue a nonblocking binary or `.bndb` open; raw binaries require a destination `bndb_path` |
| `update_analysis_and_wait` | Force analysis update and wait for completion |
| `export_program` | Export the patched binary or Binary Ninja database to disk |

By default, `open_binary` validates its paths, schedules the Binary Ninja open, and immediately returns an `operation_id` with `status="opening"`. Poll `get_binary_status(operation_id)` until it reports `ready` or `failed`. When ready, its `name` field is the final context name to pass to analysis tools. Concurrent requests for the same path reuse the active operation. Set `wait_for_analysis=true` only when legacy blocking behavior is explicitly required.

### Code Analysis (Consolidated)
| Tool | Description |
|------|-------------|
| `get_code` | Read analysis-safe code with signatures and comments; supports `decompile`, `hlil`, `mlil`, `llil`, `disasm`, and `pseudo_c` |
| `get_function_low_level_il` | Get Low-Level IL for a function |
| `get_function_signature` | Generate the native masked byte signature for a function |
| `analyze_function` | Comprehensive function analysis with control flow and complexity metrics |
| `get_basic_blocks` | Get basic block information for control flow analysis |
| `get_function_stack_layout` | Get stack frame layout with variable offsets |

#### `get_code` behavior

`get_code` is a read-only query. It does not clear `analysis_skipped`, request IL generation, or run global analysis. For `format="decompile"`, it returns already-loaded HLIL when available, then falls back through MLIL and LLIL to instruction-aligned disassembly. Use `update_analysis_and_wait` explicitly when fresh analysis is desired.

The `code` string starts with the current function signature and includes function-level and instruction-level Binary Ninja comments. The response contains:

- `function` and `address`: resolved function identity
- `format`: requested format
- `actual_format`: representation actually returned, or `null` when an explicitly requested IL is unavailable
- `fallback_used`: whether `decompile` used a lower-level representation
- `code`: rendered code, signature, and comments
- `note`: present when a fallback explains why and what was returned

### Cross-References (Consolidated)
| Tool | Description |
|------|-------------|
| `xrefs` | Unified cross-references with `direction` set to `to`, `from`, or `both`; optionally includes call relationships |

### Comments (Consolidated)
| Tool | Description |
|------|-------------|
| `comments` | **Unified comment management** - actions: `get`, `set`, `list`, `remove`, `set_function` |

### Variables (Consolidated)
| Tool | Description |
|------|-------------|
| `variables` | **Unified variable management** - actions: `list`, `create`, `rename`, `set_type`; `rename` supports local/global via `scope` |

### Types (Consolidated)
| Tool | Description |
|------|-------------|
| `types` | **Unified type management** - actions: `create`, `create_enum`, `create_typedef`, `create_class`, `add_member`, `info`, `list` |
| `get_classes` | List all classes and structures |

### Function Discovery
| Tool | Description |
|------|-------------|
| `get_functions` | List all functions with metadata |
| `search_functions_by_name` | Find functions by name pattern |
| `get_functions_advanced` | Advanced filtering by size, complexity, parameters |
| `search_functions_advanced` | Multi-target search (name, comments, calls, variables) |
| `get_function_statistics` | Comprehensive statistics for all functions |

### Symbol Management
| Tool | Description |
|------|-------------|
| `rename_symbol` | Rename functions and data variables |
| `batch_rename` | Rename multiple symbols in one operation |
| `get_namespaces` | List namespaces and symbol organization |

### Binary Information
| Tool | Description |
|------|-------------|
| `get_imports` | Import table grouped by module |
| `get_exports` | Export table with symbol information |
| `get_strings` | Paginated string extraction |
| `search_strings` | Search strings by pattern |
| `get_segments` | Memory segment layout |
| `get_sections` | Binary section information |
| `get_entry_points` | List all binary entry points |

### Data Analysis
| Tool | Description |
|------|-------------|
| `create_data_var` | Define data variables at addresses |
| `get_data_vars` | List all defined data variables |
| `get_data_at` | Read and analyze raw data |
| `search_bytes` | Search for byte patterns in binary |

### Patching
| Tool | Description |
|------|-------------|
| `patch_bytes` | Patch raw bytes in the binary at an address |
| `assemble_code` | Assemble instruction text at an address and optionally patch it |

### Navigation & Bookmarks
| Tool | Description |
|------|-------------|
| `get_current_address` | Get current cursor position with context |
| `get_current_function` | Identify function at current address |
| `bookmarks` | **Unified bookmark management** - actions: `list`, `set`, `remove` |

### Task Management (Experimental)
| Tool | Description |
|------|-------------|
| `start_task` | Create a placeholder background task record; `tool_name` dispatch is not implemented yet |
| `get_task_status` | Check status of async operations |
| `list_tasks` | List all pending/running tasks |
| `cancel_task` | Cancel a running task |

These APIs currently exercise task lifecycle management only. They do not execute the named MCP tool in the background.

---

## MCP Resources (8 Total)

Resources provide browsable, cacheable data that clients can access without tool calls.

| URI Pattern | Description |
|-------------|-------------|
| `binassist://{filename}/triage_summary` | Complete binary overview |
| `binassist://{filename}/functions` | All functions with metadata |
| `binassist://{filename}/imports` | Import table |
| `binassist://{filename}/exports` | Export table |
| `binassist://{filename}/strings` | String table |
| `binja://{filename}/info` | Binary metadata (arch, platform, entry point) |
| `binja://{filename}/segments` | Memory segments with permissions |
| `binja://{filename}/sections` | Binary sections |

---

## MCP Prompts (7 Total)

Pre-built prompts guide LLMs through structured analysis workflows.

| Prompt | Arguments | Description |
|--------|-----------|-------------|
| `analyze_function` | `function_name`, `filename` | Comprehensive function analysis workflow |
| `identify_vulnerability` | `function_name`, `filename` | Security audit checklist (memory safety, input validation, crypto) |
| `document_function` | `function_name`, `filename` | Generate Doxygen-style documentation |
| `trace_data_flow` | `address`, `filename` | Track data dependencies and taint propagation |
| `compare_functions` | `func1`, `func2`, `filename` | Diff two functions for similarity analysis |
| `reverse_engineer_struct` | `address`, `filename` | Recover structure definitions from usage patterns |
| `trace_network_data` | `filename` | Trace POSIX/Winsock send/recv for protocol analysis |

### Example: Network Protocol Analysis

The `trace_network_data` prompt guides analysis of network communication:

1. **Identify Network Functions**: Finds POSIX (`send`/`recv`/`sendto`/`recvfrom`) and Winsock (`WSASend`/`WSARecv`) calls
2. **Trace Call Stacks**: Maps application handlers down to network I/O
3. **Analyze Buffers**: Identifies protocol structures (headers, length fields, TLV encoding)
4. **Reconstruct Protocols**: Generates C struct definitions for message formats
5. **Security Assessment**: Checks for buffer overflows, integer issues, information disclosure

---

## Installation

### Prerequisites

- **Binary Ninja**: Version 5000 or higher
- **Python**: 3.10+ (typically bundled with Binary Ninja and required by the pinned MCP SDK)
- **Platform**: Windows, macOS, or Linux

NOTE: Windows users should start with: [BinAssistMCP on Windows](binassistmcp-on-windows.md)

### Option 1: Binary Ninja Plugin Manager (Recommended)

1. Open Binary Ninja
2. Navigate to **Tools** → **Manage Plugins**
3. Search for "BinAssistMCP"
4. Click **Install**
5. Restart Binary Ninja

### Option 2: Manual Installation

```bash
# Clone the repository
git clone https://github.com/symgraph/BinAssistMCP.git
cd BinAssistMCP

# Install dependencies
pip install -r requirements.txt
```

Copy to your Binary Ninja plugins directory:

| Platform | Path |
|----------|------|
| Windows | `%APPDATA%\Binary Ninja\plugins\` |
| macOS | `~/Library/Application Support/Binary Ninja/plugins/` |
| Linux | `~/.binaryninja/plugins/` |

---

## Configuration

### Binary Ninja Settings

Open **Edit** → **Preferences** → **binassistmcp**:

| Setting | Default | Description |
|---------|---------|-------------|
| `server.host` | `localhost` | Server bind address |
| `server.port` | `8000` | Server port |
| `server.transport` | `streamablehttp` | Transport: `streamablehttp` or `sse` |
| `binary.max_binaries` | `10` | Maximum concurrent binaries |
| `plugin.auto_startup` | `true` | Auto-start server on file load |

### Environment Variables

```bash
export BINASSISTMCP_SERVER__HOST=localhost
export BINASSISTMCP_SERVER__PORT=8000
export BINASSISTMCP_SERVER__TRANSPORT=streamablehttp
export BINASSISTMCP_BINARY__MAX_BINARIES=10
```

---

## Usage

### Starting the Server

**Via Binary Ninja Menu:**
1. **Tools** → **BinAssistMCP** → **Start Server**
2. Check log panel for: `BinAssistMCP server started on http://localhost:8000`

**Auto-Startup:**
Server starts automatically when Binary Ninja loads a file (configurable).

### Connecting MCP Clients

**Streamable HTTP (Default):**
```
http://localhost:8000/mcp
```

**Server-Sent Events:**
```
http://localhost:8000/sse
```

### Claude Desktop Configuration

Add to your Claude Desktop MCP configuration (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "binassist": {
      "url": "http://localhost:8000/mcp"
    }
  }
}
```

---

## Integration Examples

Most binary-specific tools require the context name in `filename`. `list_binaries` returns these names, but it is not an initialization requirement: direct filename-based calls refresh the context from Binary Ninja automatically when necessary.

### Basic Function Analysis
```
User: "Analyze the main function and explain what it does"

Claude uses:
1. list_binaries() - obtain the context filename
2. get_functions(filename='sample.bndb') - find main
3. get_code(filename='sample.bndb', function_name_or_address='main', format='decompile')
4. xrefs(filename='sample.bndb', address_or_name='main', direction='from')
5. analyze_function(filename='sample.bndb', function_name_or_address='main')
```

### Vulnerability Research
```
User: "Find buffer overflow vulnerabilities in input handling functions"

Claude uses:
1. search_functions_advanced(filename='sample.bndb', search_term='strcpy', search_in='calls')
2. get_code(filename='sample.bndb', function_name_or_address='handler', format='decompile')
3. variables(filename='sample.bndb', action='list', function_name_or_address='handler')
4. comments(filename='sample.bndb', action='set', address='0x401000', text='Unchecked copy')
```

### Protocol Reverse Engineering
```
User: "Analyze the network protocol used by this binary"

Claude uses the trace_network_data prompt:
1. Identifies send/recv call sites
2. Traces data flow from handlers to network I/O
3. Reconstructs message structures
4. Checks for network vulnerabilities
```

---

## Troubleshooting

### Server Issues

| Problem | Solution |
|---------|----------|
| Server won't start | Check port 8000 availability, verify dependencies |
| Connection refused | Ensure server is running, check firewall settings |
| A requested IL is unavailable | Run `update_analysis_and_wait`, then retry `get_code` |
| Binary name is rejected | Call `list_binaries` and use the returned context name |

### Performance

- **Memory usage**: Reduce `max_binaries` setting
- **Code retrieval**: `get_code` returns loaded analysis immediately and falls back rather than triggering analysis

### Logs

Check Binary Ninja's Log panel for detailed error messages.

---

## Contributing

1. Fork the repository
2. Create a feature branch
3. Follow existing code patterns (Pydantic models, type hints, docstrings)
4. Test with multiple binary types
5. Submit a pull request

---

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.