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
- 36 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
- Analysis Caching: LRU cache with binary-scoped invalidation for improved performance
- Async Task Support: Non-blocking execution for long-running operations
- 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 - 36 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 # LRU analysis cache with invalidation
├── tasks.py # Async task manager for long-running operations
├── logging.py # Binary Ninja logging integration
└── utils.py # Utility functions
__init__.py # Plugin entry point (root level)
BinAssistMCP provides 36 tools organized into functional categories. Tools include MCP annotations (readOnlyHint, idempotentHint) to help clients make informed decisions.
Binary Management
| Tool | Description |
|---|
list_binaries | List all loaded binary files |
get_binary_status | Check analysis status and metadata |
update_analysis_and_wait | Force analysis update and wait for completion |
Code Analysis (Consolidated)
| Tool | Description |
|---|
get_code | Unified code retrieval - supports formats: decompile, hlil, mlil, llil, disasm, pseudo_c |
get_function_low_level_il | Get Low-Level IL 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 |
Cross-References (Consolidated)
| Tool | Description |
|---|
xrefs_tool | Unified cross-references - actions: refs_to, refs_from, call_graph |
| Tool | Description |
|---|
comments_tool | Unified comment management - actions: get, set, list, remove, set_function |
Variables (Consolidated)
| Tool | Description |
|---|
variables_tool | Unified variable management - actions: list, create, rename, set_type |
Types (Consolidated)
| Tool | Description |
|---|
types_tool | Unified type management - actions: create, create_enum, create_typedef, create_class, add_member, get_info, list |
get_classes | List all classes and structures |
Function Discovery
| Tool | Description |
|---|
get_functions | List all functions with metadata (paginated) |
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 |
| Tool | Description |
|---|
get_imports | Import table grouped by module |
get_exports | Export table with symbol information |
get_strings | String extraction with filtering |
search_strings | Search strings by pattern |
get_segments | Memory segment layout |
get_sections | Binary section information |
Data Analysis
| Tool | Description |
|---|
create_data_var | Define data variables at addresses |
get_data_vars | List all defined data variables |
get_data_at_address | Read and analyze raw data |
search_bytes | Search for byte patterns in binary |
Navigation
| Tool | Description |
|---|
get_current_address | Get current cursor position with context |
get_current_function | Identify function at current address |
Task Management
| Tool | Description |
|---|
get_task_status | Check status of async operations |
list_tasks | List all pending/running tasks |
cancel_task | Cancel a running task |
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:
- Identify Network Functions: Finds POSIX (
send/recv/sendto/recvfrom) and Winsock (WSASend/WSARecv) calls
- Trace Call Stacks: Maps application handlers down to network I/O
- Analyze Buffers: Identifies protocol structures (headers, length fields, TLV encoding)
- Reconstruct Protocols: Generates C struct definitions for message formats
- Security Assessment: Checks for buffer overflows, integer issues, information disclosure
Installation
Prerequisites
- Binary Ninja: Version 4000 or higher
- Python: 3.8+ (typically bundled with Binary Ninja)
- Platform: Windows, macOS, or Linux
NOTE: Windows users should start with: BinAssistMCP on Windows
Option 1: Binary Ninja Plugin Manager (Recommended)
- Open Binary Ninja
- Navigate to Tools → Manage Plugins
- Search for "BinAssistMCP"
- Click Install
- Restart Binary Ninja
Option 2: Manual Installation
git clone https://github.com/jtang613/BinAssistMCP.git
cd BinAssistMCP
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 | 9090 | 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
export BINASSISTMCP_SERVER__HOST=localhost
export BINASSISTMCP_SERVER__PORT=9090
export BINASSISTMCP_SERVER__TRANSPORT=streamablehttp
export BINASSISTMCP_BINARY__MAX_BINARIES=10
Usage
Starting the Server
Via Binary Ninja Menu:
- Tools → BinAssistMCP → Start Server
- Check log panel for:
BinAssistMCP server started on http://localhost:9090
Auto-Startup:
Server starts automatically when Binary Ninja loads a file (configurable).
Connecting MCP Clients
Streamable HTTP (Default):
http://localhost:9090/mcp
Server-Sent Events:
http://localhost:9090/sse
Claude Desktop Configuration
Add to your Claude Desktop MCP configuration (claude_desktop_config.json):
{
"mcpServers": {
"binassist": {
"url": "http://localhost:9090/mcp"
}
}
}
Integration Examples
Basic Function Analysis
User: "Analyze the main function and explain what it does"
Claude uses:
1. get_functions() - find main
2. get_code(format='decompile') - get readable code
3. xrefs_tool(action='refs_from') - find called functions
4. analyze_function() - get complexity metrics
Vulnerability Research
User: "Find buffer overflow vulnerabilities in input handling functions"
Claude uses:
1. search_functions_advanced(search_in='calls') - find memcpy/strcpy callers
2. get_code(format='decompile') - examine implementations
3. variables_tool(action='list') - check buffer sizes
4. comments_tool(action='set') - document findings
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 9090 availability, verify dependencies |
| Connection refused | Ensure server is running, check firewall settings |
| Tools return errors | Wait for analysis completion, verify binary is loaded |
- Slow decompilation: Results are cached; second request is faster
- Memory usage: Reduce
max_binaries setting
- Long operations: Check task status with
get_task_status
Logs
Check Binary Ninja's Log panel for detailed error messages.
Contributing
- Fork the repository
- Create a feature branch
- Follow existing code patterns (Pydantic models, type hints, docstrings)
- Test with multiple binary types
- Submit a pull request
License
This project is licensed under the MIT License - see the LICENSE file for details.
