EDB Debugger MCP

About

EDB (Evan's Debugger) is a feature-rich, open-source GUI debugger for Linux (x86/x86-64), known for its intuitive interface, powerful plugin system (22 plugins), and extensive debugging capabilities — breakpoints, memory analysis, ROP tool, heap analyzer, and more. However, EDB has always been limited to manual GUI interaction — until now.

EDB Debugger MCP bridges EDB's debugging engine with modern AI via the Model Context Protocol (MCP). Every EDB feature is exposed as a tool callable by an AI assistant — Claude Desktop, Cursor, or any MCP host — effectively giving AI a debugger's intuition. The server exposes 26 composite debugging tools (19 edb_ + 7 pwntools_) that replace 157 flat primitives using parameter-driven dispatch for minimal context overhead (~4× token savings vs flat tool catalogs).

Behind the scenes, it translates AI requests into GDB MI commands via a high-performance async backend, then formats results back as structured data. Combined with pwntools integration (7 composite tools covering ELF analysis, ROP, shellcode, assembly, packing, tubes, and utilities), it becomes a complete AI-powered reverse engineering workstation.

EDB · GDB · MCP · FastMCP · pwntools · Binary Ninja

Table of Contents

• Quick Start

• Features

• Use Cases

• Requirements

• Installation

• Usage

  • Standalone

  • Claude Desktop Integration

  • Other MCP Hosts

• Docker Usage

• Architecture

• pwntools Tools

• EDB Plugin Mapping

• Binary Ninja Integration

• Ghidra Integration

• Web UI

• CTF Examples

• x64dbg Integration

• IDA Pro Integration

• VS Code Extension

• Project Structure

• Tool Reference

• License

Quick Start

pip install edb-debugger-mcp
edb-debugger-mcp &

Then add to Claude Desktop config and ask: "Load /bin/ls, find ROP gadgets with pop eax, and generate execve shellcode" — the AI handles the rest.

Features

• Program Control — Load, run, pause, continue, restart, attach/detach, kill

• Breakpoints — Software/hardware breakpoints, watchpoints (read/write/access), conditional, ignore count, commands, catchpoints, export/import

• Step Operations — Step into/over/out, step instruction, step-over instruction, reverse step/continue

• Register Management — Read/write all CPU/FPU/SIMD registers, formatted dump, flag analysis, changed registers

• Memory Operations — Hex dump, write memory/bytes, fill pattern, search, compare regions, set permissions

• Disassembly — Full/range disassembly, current instruction, assembly patching, NOP fill

• Stack Analysis — Stack dump, push/pop/modify, frame info, backtrace, arguments, locals

• Symbol Resolution — Symbol lookup, modules, sections, entry point, symbol map, binary info

• Thread Support — List/switch threads, process info, thread info

• Expression Evaluation — C expression, variable get/set, string reading, type info (ptype/whatis)

• Code Analysis — Source listing, function info/bounds, references, ROP gadgets, basic blocks, CFG

• Code Patching — Assemble instruction, NOP range, fill zero, label address, comments/annotations

• Session Management — Save/load sessions, bookmark addresses, export/import breakpoints

• Remote Debugging — Connect to remote GDB server, generate core dumps

• Environment — Get/set/unset env vars, set working directory, TTY, signal handling

• Configuration — ASLR toggle, lazy binding toggle, debug output, session logging, signal ignore list

• Utility — Binary string convert (hex↔ascii↔utf-16), file↔VA offset convert, font config

• Pwntools Integration — Assembly/disassembly (Keystone/Capstone), ELF analysis, ROP gadget search, shellcode generation, cyclic pattern, format string payloads, pack/unpack

Use Cases

• CTF Exploit Development — cyclic pattern → offset discovery → ROP gadgets → shellcode → assemble

• Malware Analysis — attach → breakpoint → memory dump → core dump

• Bug Hunting — ASLR disable → run → memory search → heap analysis

• Vulnerability Research — expression eval → stack inspection → instruction analysis → function call

• Reverse Engineering — disassemble → CFG → string search → symbol lookup

Requirements

• Python >= 3.10

• GDB (GNU Debugger) installed on the system

• Linux (x86-64 recommended)

Installation

# Clone the repository
git clone https://github.com/oakkaya/edb-debugger-mcp.git
cd edb-debugger-mcp

# Install dependencies
pip install -r requirements.txt

# (Optional) Install with pip
pip install -e .

Usage

Standalone

python edb_debugger_mcp.py

This starts the MCP server on stdio, ready to accept MCP protocol messages.

Testing

# Compile a test binary
gcc -g -o /tmp/test_bin /path/to/test.c

# Then run the server manually or use an MCP client

Claude Desktop Integration

If installed via pip:

{
  "mcpServers": {
    "edb-debugger-mcp": {
      "command": "edb-debugger-mcp"
    }
  }
}

If installed from source:

{
  "mcpServers": {
    "edb-debugger-mcp": {
      "command": "python",
      "args": ["/path/to/edb_debugger_mcp/edb_debugger_mcp.py"]
    }
  }
}

Config file location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Other MCP Hosts

The same server works with any MCP-compatible host. Example configurations:

opencode (~/.config/opencode/config.json):

{
  "mcpServers": {
    "edb-debugger-mcp": {
      "command": "edb-debugger-mcp"
    }
  }
}

Cursor (Project Settings → MCP Servers):

{
  "mcpServers": {
    "edb-debugger-mcp": {
      "command": "edb-debugger-mcp"
    }
  }
}

Continue.dev (~/.continue/config.json):

{
  "experimental": {
    "mcpServers": {
      "edb-debugger-mcp": {
        "command": "edb-debugger-mcp"
      }
    }
  }
}

Docker Usage

A pre-built Docker image is available on GitHub Container Registry.

# Pull the latest image
docker pull ghcr.io/oakkaya/edb-debugger-mcp:latest

# Run the MCP server (stdio mode, for MCP hosts)
docker run -i ghcr.io/oakkaya/edb-debugger-mcp

# Run with a specific version tag
docker run -i ghcr.io/oakkaya/edb-debugger-mcp:latest

# Run interactively with a shell for debugging
docker run --rm -it \
  --security-opt seccomp=unconfined \
  --cap-add=SYS_PTRACE \
  ghcr.io/oakkaya/edb-debugger-mcp /bin/bash

The image is built from python:3.13-slim with GDB pre-installed. It is automatically rebuilt and published on every GitHub release (v* tag).

Architecture

┌─────────────────────┐     MCP Protocol      ┌──────────────────────┐
│   MCP Client        │ ◄──────────────────►  │   FastMCP Server     │
│ (Claude, Cursor)    │     stdio JSON-RPC    │   edb_debugger_mcp.py│
└─────────────────────┘                       └──────────┬───────────┘
                                                          │
                                                      GDB MI
                                                   (--interpreter=mi2)
                                                          │
                                                 ┌────────┴───────────┐
                                                 │   GDB Backend      │
                                                 │   gdb_backend.py   │
                                                 │  (async subprocess)│
                                                 │  MI parser + 123   │
                                                 │  public methods    │
                                                 └────────────────────┘

The server uses GDB's MI (Machine Interface) protocol (--interpreter=mi2) to communicate with GDB as a subprocess. The backend:

• Sends MI/CLI commands via stdin, parses structured MI responses

• Handles *stopped async events for breakpoint hits

• Manages process lifecycle (start, kill, detach)

• Provides readelf-based file offset ↔ VA conversion

Note: The EDB action/dialog/view counts listed in this README cover all of EDB's UI elements. Since this project is an MCP server, UI-only features (About dialog, font selector, Reset UI, window layout) cannot be mapped. All functional debugging capabilities (breakpoint, register, memory, stack, thread, expression, patching, analysis, ROP, session) are 100% covered.

pwntools Tools

The server integrates pwntools — the CTF/exploit development framework — as 50 MCP tools callable alongside the EDB debugger tools.

Usage: ask the AI "Find ROP gadgets with pop rdi" or "Generate x64 execve shellcode" — no separate setup needed.

EDB Plugin Mapping

Binary Ninja Integration

⚠ Experimental / untested — Binary Ninja is a commercial product (not available in this environment). The plugin code is structurally complete and follows the BN plugin API, but has not been verified at runtime. PRs welcome.

The binaryninja_mcp/ directory contains a full Binary Ninja plugin that bridges the decompiler with the live debugger. Features:

• Register overlay — HLIL comments with live register values

• Single-click breakpoints — Right-click to toggle software/hardware breakpoints

• In-place patching — NOP, assemble, range-NOP from the disassembly context menu

• Step control — Step into/over/out, run, pause via Plugins menu

• Sidebar widget — Live register summary in the "EDB Debugger" tab

Install: ln -s $(pwd)/binaryninja_mcp ~/.binaryninja/plugins/edb-debugger-bridge

Ghidra Integration

⚠ Experimental / untested — Requires pyhidra. Plugin is structurally complete but not verified at runtime. PRs welcome.

The ghidra_mcp/ directory contains a Ghidra Python bridge that follows the same pattern as BN. Features:

• Start/Stop Bridge — Connect/disconnect from the MCP server

• Toggle Breakpoint — Set/clear breakpoints at the cursor address

• In-place patching — NOP, assemble instructions

• Step/run control — Step into/over, run, pause

• Register & memory inspection — Live register values, memory hex dump

Install: in Ghidra with pyhidra, run ghidra_mcp/ghidra_bridge.py via the Python interpreter, then use the newly registered actions from the right-click menu.

Web UI

⚠ Experimental

The web_ui/ directory provides a browser-based debugger frontend (FastAPI + vanilla JS). No JS framework required.

cd web_ui
pip install -r requirements.txt
python server.py
# → http://localhost:8000

Features:

• Categorized tool sidebar — Program, Breakpoints, Run/Step, Registers/Memory, Analysis, Pwntools

• Dynamic parameter forms — Tools with arguments show input fields auto-generated from the tool schema

• Dark theme — Clean, readable interface

• Live results — Output streams into the result panel with auto-scroll

REST API

The Web UI exposes a REST API used by the frontend. All endpoints return JSON unless noted.

x64dbg Integration

⚠ Experimental / untested — Windows-only. Requires x64dbg with x64dbgpy. No test environment available.

The x64dbg_mcp/ directory contains an x64dbgpy plugin. Features:

• Start/Stop Bridge — Connect to the MCP server

• Breakpoint control — Toggle, clear all

• Patching — NOP, assemble at cursor

• Step/run — Step into/over, run, pause

• Inspection — Registers, memory at selection

Install: copy x64dbg_mcp/ to x64dbg's py-plugins/ directory. The "EDB Bridge" submenu appears under Plugins.

Quick Start

# Install
pip install edb-debugger-mcp

# Start the MCP server (standalone)
edb-debugger-mcp

# Or with Web UI
pip install "edb-debugger-mcp[web]"
python3 -m web_ui.server

3-step CTF solve with AI:

User:  Load /challenge/bof and analyze it
AI:    → edb_load_program(path="/challenge/bof")
       → edb_disassemble("main")  → finds gets() call
       → edb_list_functions()     → finds win() at 0x4011b6

User:  Build exploit
AI:    → pwntools_cyclic(200)     → generates pattern
       → pwntools_cyclic_find("0x6161616c") → offset = 136
       → pwntools_flat([0xdeadbeef]*34 + [0x4011b6]) → payload

User:  Test it
AI:    → edb_run(args=$(python3 -c "print('A'*136 + '\xb6\x11\x40')"))
       → edb_set_breakpoint("win")
       → edb_continue() → breaks at win → flag printed!

IDA Pro Integration

✅ Tested with IDA Pro 9.3 — IDAPython imports (ida_pro, idaapi, idc, idautils), all 13 actions register under Edit -> EDB Debugger, MCP subprocess bridge connects with 26 composite tools, step/run/breakpoint/patch actions work, headless mode works with ida -c -A -S<script> under xvfb.

The ida_mcp/ directory contains an IDAPython plugin that connects IDA Pro to the MCP server. Features:

• Start/Stop Bridge — Launch and terminate the MCP subprocess

• Toggle Breakpoint (F2) — Set/remove software breakpoint at cursor

• Clear All Breakpoints — Remove all breakpoints

• Patching — NOP or assemble instruction at current address

• Step/run control — Step into (F11), step over (F10), step out (Shift+F11), run (F5), pause

• Inspection — Show register values, read memory at cursor

Install: copy ida_mcp/ to IDA's plugin directory:

cp -r ida_mcp ~/.idapro/plugins/edb_debugger_bridge

After starting the bridge (Edit -> EDB Debugger -> Start Bridge), all actions are available from the Edit -> EDB Debugger menu.

VS Code Extension

⚠ Experimental

The vscode-edb-mcp/ directory contains a VS Code extension that provides a debugger frontend inside VS Code. Features:

• Start/Stop Bridge — Spawn and kill the MCP subprocess

• Debugger Panel — WebView panel for debugging commands

• Execution control — Run/continue (F5), pause, step into (F11), step over (F10)

• Breakpoint management — Set/clear breakpoints

• Register/Memory inspection — View register state and memory

• Status bar indicator — Shows bridge connection state (connected/disconnected)

Build and install:

cd vscode-edb-mcp
npm install
npm run compile
code --install-extension edb-debugger-mcp-1.0.0.vsix

The extension registers commands under the EDB: prefix and shows a status bar item.

Project Structure

edb-debugger-mcp/
├── edb_debugger_mcp/        # Package: FastMCP server (19 composite edb_ tools)
│   ├── __init__.py           # Entry point + main()
│   ├── _mcp.py               # FastMCP instance + GDB backend init
│   ├── composite_tools.py    # 26 composite tools (19 edb_ + 7 pwntools_)
│   ├── gdb_backend.py        # GDB MI backend (172 public methods, MI parser, session mgmt)
│   └── edb_models.py         # Pydantic models for tool parameters
├── web_ui/                    # Web debugger frontend (FastAPI + htmx, browser-based)
│   ├── server.py              # FastAPI app, tool categories, multi-page routing
│   └── templates/             # Static HTML + JavaScript frontend
├── binaryninja_mcp/           # Binary Ninja plugin (register overlay, right-click BP/patch, step)
├── ghidra_mcp/                # Ghidra bridge (pyhidra-based, same MCP client)
├── ida_mcp/                   # IDA Pro plugin (IDAPython bridge with breakpoint/patch/step)
├── x64dbg_mcp/                # x64dbgpy plugin (Windows debugger bridge)
├── vscode-edb-mcp/            # VS Code extension (debugger panel, commands, status bar)
├── scripts/                   # Utility scripts
│   └── generate_tool_table.py # Auto-generates markdown tool table
├── examples/                  # 10 CTF challenges
│   ├── ret2win/               #   Buffer overflow → call win function
│   ├── format-string/         #   Format string → GOT overwrite
│   ├── crackme/               #   Static password analysis
│   ├── rop-chain/             #   ROP chain ret2libc (NX enabled)
│   ├── shellcode-injection/   #   Shellcode on executable stack
│   ├── off-by-one/            #   Off-by-one overwrites adjacent variable
│   ├── heap-uaf/              #   Use-after-free → function pointer overwrite
│   ├── integer-overflow/      #   Signed check bypass → OOB write
│   ├── nx-bypass/             #   ROP mprotect + shellcode
│   └── canary-leak/           #   Format string leak + BOF with canary
├── tests/                     # 452 tests (pytest + pytest-asyncio)
├── CHANGELOG.md               # Version history
├── requirements.txt           # Python dependencies
├── README.md                  # This file
├── LICENSE                    # MIT License
└── .gitignore                 # Git ignore rules

CTF Examples

The examples/ directory contains 10 CTF-style challenges that showcase different exploitation techniques and the corresponding EDB MCP tools used to solve them.

Each challenge includes source code, a compiled binary, and a solve script. Run from the challenge directory:

cd examples/ret2win
python solve.py

Tool Reference (26 tools)

Execution & Process (1 tool)

Stepping (1 tool)

Tracing (1 tool)

Breakpoints (1 tool)

Registers (1 tool)

Memory (1 tool)

Disassembly (1 tool)

Stack (1 tool)

Symbols (1 tool)

Expressions (1 tool)

Debug Info (1 tool)

Threads (1 tool)

Modules & Plugins (1 tool)

Analysis (1 tool)

Annotations (1 tool)

Session (1 tool)

Patching (1 tool)

Configuration (1 tool)

Environment (1 tool)

pwntools Tools (7 composite)

License

MIT License — see LICENSE for details.