Binary Analysis MCP Server

A comprehensive binary analysis tool that integrates with radare2 to provide deep insights into binary files. This MCP (Model Context Protocol) server enables Claude to analyze executable files, shared libraries, and other binary objects with tools for disassembly, string extraction, entropy analysis, and cross-reference mapping.

Overview

This server provides access to radare2's powerful binary analysis capabilities through a unified interface:

• Binary Information - File format, architecture, OS, and metadata
• String Extraction - Find embedded strings and data
• Import/Export Analysis - Identify dependencies and exported symbols
• Section Analysis - Examine binary sections with entropy calculation
• Disassembly - Decompile machine code to assembly language
• Cross-references - Trace function calls and data references
• Entropy Detection - Identify packed or encrypted sections
• Function Discovery - Locate and analyze functions within binaries

Perfect for malware analysis, reverse engineering, vulnerability research, and binary security assessment.

Tools

| Tool | r2 Command | Description | |------|-----------|-------------| | r2_info | iIj | Get binary file information (architecture, format, OS) | | r2_strings | izj | Extract strings from binary with configurable minimum length | | r2_imports | iij | List imported functions and required libraries | | r2_exports | iEj | List exported symbols and public functions | | r2_sections | iSj | Show binary sections with sizes and entropy | | r2_disassemble | aaa, pd | Disassemble function or address range to assembly | | r2_xrefs | axt, axf | Find cross-references to/from specific addresses | | r2_entropy_map | p=e | Generate entropy visualization for packing detection | | r2_functions | aaa, aflj | List detected functions with addresses and sizes |

Binary File Info

Get comprehensive information about a binary file including architecture, format, OS, and class.

Input Parameters:

{
  file_path: string       // Absolute path to the binary file
  timeout: number         // Timeout in seconds (default: 120, range: 10-300)
}

Example Request:

{
  "file_path": "/usr/bin/ls",
  "timeout": 60
}

Example Output:

{
  "arch": "x86",
  "bits": 64,
  "os": "linux",
  "endian": "LE",
  "type": "EXEC",
  "class": "ELF64",
  "machine": "x86-64",
  "compiler": "gcc",
  "relro": "partial",
  "nx": true,
  "canary": true,
  "pie": true
}

String Extraction

Extract embedded strings from a binary file with filtering by minimum length.

Input Parameters:

{
  file_path: string       // Absolute path to the binary file
  min_length: number      // Minimum string length (1-100, default: 6)
  encoding: string        // String encoding: "utf8" or "ascii" (default: "utf8")
  timeout: number         // Timeout in seconds (default: 120, range: 10-300)
}

Example Request:

{
  "file_path": "/usr/bin/cat",
  "min_length": 8,
  "encoding": "utf8",
  "timeout": 60
}

Example Output:

[
  {
    "vaddr": 4202496,
    "paddr": 2496,
    "size": 11,
    "ordinal": 1,
    "string": "/lib64/ld-linux",
    "length": 15,
    "type": "ascii"
  },
  {
    "vaddr": 4202512,
    "paddr": 2512,
    "size": 7,
    "ordinal": 2,
    "string": "libc.so.6",
    "length": 9,
    "type": "ascii"
  },
  {
    "vaddr": 4203052,
    "paddr": 3052,
    "size": 8,
    "ordinal": 3,
    "string": "fwrite",
    "length": 6,
    "type": "ascii"
  }
]

Import Analysis

List all imported functions and required libraries for a binary.

Input Parameters:

{
  file_path: string       // Absolute path to the binary file
  timeout: number         // Timeout in seconds (default: 120, range: 10-300)
}

Example Request:

{
  "file_path": "/usr/bin/strings",
  "timeout": 60
}

Example Output:

[
  {
    "ordinal": 1,
    "bind": "GLOBAL",
    "type": "FUNC",
    "name": "printf",
    "plt": 4202976,
    "got": 4208040,
    "lib": "libc.so.6"
  },
  {
    "ordinal": 2,
    "bind": "GLOBAL",
    "type": "FUNC",
    "name": "malloc",
    "plt": 4202992,
    "got": 4208048,
    "lib": "libc.so.6"
  },
  {
    "ordinal": 3,
    "bind": "GLOBAL",
    "type": "FUNC",
    "name": "free",
    "plt": 4203008,
    "got": 4208056,
    "lib": "libc.so.6"
  }
]

Export Analysis

List exported symbols and public functions from a binary or library.

Input Parameters:

{
  file_path: string       // Absolute path to the binary file
  timeout: number         // Timeout in seconds (default: 120, range: 10-300)
}

Example Request:

{
  "file_path": "/usr/lib/libcrypto.so.3",
  "timeout": 60
}

Example Output:

[
  {
    "ordinal": 1,
    "bind": "GLOBAL",
    "type": "FUNC",
    "name": "EVP_CIPHER_CTX_new",
    "vaddr": 265984,
    "size": 45
  },
  {
    "ordinal": 2,
    "bind": "GLOBAL",
    "type": "FUNC",
    "name": "EVP_CIPHER_CTX_free",
    "vaddr": 266032,
    "size": 32
  },
  {
    "ordinal": 3,
    "bind": "GLOBAL",
    "type": "FUNC",
    "name": "EVP_EncryptInit_ex",
    "vaddr": 266064,
    "size": 128
  }
]

Section Analysis

Examine binary sections including code, data, and resource sections with entropy calculations.

Input Parameters:

{
  file_path: string       // Absolute path to the binary file
  timeout: number         // Timeout in seconds (default: 120, range: 10-300)
}

Example Request:

{
  "file_path": "/usr/bin/bash",
  "timeout": 60
}

Example Output:

[
  {
    "name": ".text",
    "size": 524288,
    "vaddr": 4202496,
    "paddr": 2496,
    "align": 16,
    "flags": "rx",
    "entropy": 5.87
  },
  {
    "name": ".data",
    "size": 65536,
    "vaddr": 4726784,
    "paddr": 524784,
    "align": 8,
    "flags": "rw",
    "entropy": 3.21
  },
  {
    "name": ".rodata",
    "size": 262144,
    "vaddr": 4465664,
    "paddr": 263664,
    "align": 1,
    "flags": "r",
    "entropy": 4.45
  },
  {
    "name": ".bss",
    "size": 131072,
    "vaddr": 4792320,
    "paddr": 0,
    "align": 32,
    "flags": "rw",
    "entropy": 0.0
  }
]

Disassembly

Disassemble a function or specific address range to assembly language.

Input Parameters:

{
  file_path: string       // Absolute path to the binary file
  address: string         // Memory address in hex (e.g., "0x00401000"), optional
  count: number           // Number of instructions to show (1-1000, default: 100)
  timeout: number         // Timeout in seconds (default: 120, range: 10-300)
}

Example Request:

{
  "file_path": "/usr/bin/echo",
  "address": "0x1000",
  "count": 20,
  "timeout": 60
}

Example Output:

Disassembly:
0x00001000    48 89 e5           mov rbp, rsp
0x00001003    48 83 ec 20        sub rsp, 0x20
0x00001007    89 7d ec           mov dword [rbp - 0x14], edi
0x0000100a    48 89 75 e0        mov qword [rbp - 0x20], rsi
0x0000100e    8b 05 cc 2f 00 00  mov eax, dword [rip + 0x2fcc]
0x00001014    83 c0 01           add eax, 1
0x00001017    89 05 c3 2f 00 00  mov dword [rip + 0x2fc3], eax
0x0000101d    b8 00 00 00 00     mov eax, 0
0x00001022    c9                 leave
0x00001023    c3                 ret

Cross-references

Find all references to or from a specific memory address.

Input Parameters:

{
  file_path: string       // Absolute path to the binary file
  address: string         // Memory address in hex (e.g., "0x00401000")
  direction: string       // "to" for references pointing to this address, "from" for references from it (default: "to")
  timeout: number         // Timeout in seconds (default: 120, range: 10-300)
}

Example Request:

{
  "file_path": "/usr/bin/wget",
  "address": "0x404050",
  "direction": "to",
  "timeout": 60
}

Example Output:

Cross-references to 0x404050:
0x00401234 call 0x404050 [CALL]
0x00401567 jmp 0x404050 [JUMP]
0x00402abc call 0x404050 [CALL]
0x00403def mov rax, [rel 0x404050] [DATA]

Entropy Map

Generate entropy visualization for a binary to detect packed or encrypted sections.

Input Parameters:

{
  file_path: string       // Absolute path to the binary file
  timeout: number         // Timeout in seconds (default: 120, range: 10-300)
}

Example Request:

{
  "file_path": "/usr/bin/gzip",
  "timeout": 60
}

Example Output:

Entropy Map:
0x0000 |**...**|...**|...**|
0x1000 |.**...|**.|*.*|**..
0x2000 |***|.*|***|*.|***|
0x3000 |...**|*|*|**|..|**
0x4000 |*|..***|.**|*|**.*.

Function Discovery

List all detected functions in a binary with their addresses, sizes, and metadata.

Input Parameters:

{
  file_path: string       // Absolute path to the binary file
  timeout: number         // Timeout in seconds (default: 120, range: 10-300)
}

Example Request:

{
  "file_path": "/usr/bin/id",
  "timeout": 60
}

Example Output:

[
  {
    "offset": 4202560,
    "size": 42,
    "name": "sym.main",
    "type": "fcn",
    "nargs": 2,
    "nlocals": 4,
    "stack": 16,
    "cc": "amd64"
  },
  {
    "offset": 4202602,
    "size": 87,
    "name": "sym.getpwuid",
    "type": "fcn",
    "nargs": 1,
    "nlocals": 2,
    "stack": 8,
    "cc": "amd64"
  },
  {
    "offset": 4202689,
    "size": 156,
    "name": "sym.print_user_info",
    "type": "fcn",
    "nargs": 3,
    "nlocals": 5,
    "stack": 32,
    "cc": "amd64"
  }
]

Configuration

Environment Variables

This server requires radare2 to be installed and accessible in the system PATH. No API keys are needed.

# Optional: Set custom radare2 binary path if not in PATH
export R2_BIN="/usr/bin/r2"

File Access Restrictions

The server implements strict security controls:

• Absolute file paths required
• Maximum file size: 500MB
• Blocked paths: /etc/shadow, /proc, /sys, /dev
• Symbolic link resolution to prevent escapes
• File existence validation

Prerequisites

• Bun runtime (version 1.x or later)
• Node.js 18+ (alternative runtime)
• radare2 binary installed and available in PATH

Installing radare2

On macOS:

brew install radare2

On Ubuntu/Debian:

sudo apt-get install radare2

On Fedora/RHEL:

sudo dnf install radare2

From source:

git clone https://github.com/radareorg/radare2.git
cd radare2
./sys/install.sh

Installation

Prerequisites

• Bun runtime (version 1.x or later)
• Node.js 18+ (alternative runtime)
• radare2 installed and accessible in PATH

Steps

1. Clone or download this repository:

git clone <repo-url>
cd binary-analysis

2. Install dependencies:

bun install

3. Build the project:

bun run build

4. Verify radare2 is installed:

r2 --version

5. Run the server:

bun run start

The server will start listening on stdio transport.

Usage

Running the Server

Start the server with Bun:

bun run src/index.ts

The server implements the Model Context Protocol (MCP) and communicates via stdio transport. It can be integrated with Claude or other MCP clients.

Claude Desktop Configuration

Add the server to your Claude Desktop configuration at ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "binary-analysis": {
      "command": "bun",
      "args": [
        "run",
        "/path/to/binary-analysis/src/index.ts"
      ]
    }
  }
}

Claude Code MCP Settings

Configure the server in Claude Code's MCP settings (typically in .mcp.json or via settings UI):

{
  "servers": {
    "binary-analysis": {
      "transport": "stdio",
      "command": "bun",
      "args": ["run", "/path/to/binary-analysis/src/index.ts"]
    }
  }
}

Example Usage in Claude

Once configured, you can use the tools directly in conversations with Claude:

Request: "Analyze the binary /usr/bin/ls and tell me about its architecture and what libraries it imports"

Claude will call:

{
  "tool": "r2_info",
  "input": {
    "file_path": "/usr/bin/ls",
    "timeout": 120
  }
}

Then:

{
  "tool": "r2_imports",
  "input": {
    "file_path": "/usr/bin/ls",
    "timeout": 120
  }
}

Request: "Extract strings from /usr/bin/curl that are at least 10 characters long"

Claude will call:

{
  "tool": "r2_strings",
  "input": {
    "file_path": "/usr/bin/curl",
    "min_length": 10,
    "encoding": "utf8",
    "timeout": 120
  }
}

Request: "Show me the disassembly of the main function in /usr/bin/sha256sum"

Claude will call:

{
  "tool": "r2_disassemble",
  "input": {
    "file_path": "/usr/bin/sha256sum",
    "timeout": 120
  }
}

Security

This server implements comprehensive input validation and security measures to prevent abuse and control radare2 execution:

Command Whitelisting

Only specific, read-only radare2 commands are allowed:

Allowed Commands:

• iI, iIj - Binary info (JSON)
• iz, izj, izz, izzj - Strings (JSON)
• ii, iij - Imports (JSON)
• iE, iEj - Exports (JSON)
• iS, iSj, iSS, iSSj - Sections (JSON)
• pdf, pd, pdj - Disassembly (JSON)
• axt, axtj, axf, axfj - Cross-references (JSON)
• p=e - Entropy visualization
• afl, aflj - Function list (JSON)
• aaa, aa - Analysis commands
• e - Print environment
• s - Seek to address

Blocked Write/Exec Commands

The server explicitly rejects:

• Shell escapes starting with ! or #
• Write operations (w* commands)
• File operations (o and oo+)
• Script/macro execution
• Shell command injection

Blocked Pattern: ^[!#]|^oo\+|^w[a-z]?[\s]|^o\s

File Path Validation

Absolute Paths Required

• Only absolute file paths accepted
• Symbolic links are resolved to prevent escapes
• Relative paths rejected

File Existence & Type Checks

• File must exist on disk
• Must be a regular file (no directories)
• No special files (/etc/shadow, /proc, /sys, /dev)

Size Limits

• Maximum file size: 500MB
• Prevents analysis of excessively large files

Input Validation

Address Validation

• Hexadecimal format required (0x prefix optional)
• Range: 0x0 to 0xffffffffffffffff

Count Validation

• Integer between 1 and 1000
• Default: 100 instructions
• Prevents unbounded output

Timeout Validation

• Integer between 10 and 300 seconds
• Default: 120 seconds
• Prevents runaway processes

Encoding Validation

• Only "utf8" and "ascii" allowed
• Prevents encoding-based injection

String Length Filter

• Minimum length 1, maximum 100
• Prevents returning excessive data

What Gets Blocked

The server rejects:

• Invalid file paths (relative, non-existent)
• Files larger than 500MB
• Access to system directories
• Write and execution commands
• Shell metacharacters in commands
• Oversized output parameters
• Invalid address formats
• Invalid timeout values

Error Handling

• Invalid inputs return descriptive error messages
• radare2 errors are caught and reported
• Timeouts are handled gracefully
• Command failures prevent execution
• Missing files trigger validation errors

License

ISC License - see LICENSE file for details