Edb Debugger Mcp

EDB Debugger MCP

[](https://github.com/oakkaya/edb-debugger-mcp/actions) [](https://pypi.org/project/edb-debugger-mcp/) [](https://pypi.org/project/edb-debugger-mcp/) [](LICENSE) [](https://www.sourceware.org/gdb/) [](https://modelcontextprotocol.io) [](https://github.com/oakkaya/edb-debugger-mcp/pkgs/container/edb-debugger-mcp) [](CHANGELOG.md)

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.

Complete RE workflow: load binary → disassemble → ROP search → set breakpoint → run → read registers → dump stack → backtrace → generate shellcode.

Tool call arguments and their structured results displayed side by side for clarity.

| Stat | Value | |------|-------| | Total tools | 26 (19 edb composite + 7 pwntools composite) — replaces 207 flat tools | | Test count | 452 (pytest, 4 Python versions) | | EDB feature coverage | 22/22 plugins · 29/29 actions · 13/13 dialogs · 6/6 views | | Code size | ~9000 LOC · 100 Pydantic models · 182 backend methods |

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

Table of Contents

• [Quick Start](#quick-start)
• [Features](#features)
• [Use Cases](#use-cases)
• [Requirements](#requirements)
• [Installation](#installation)
• [Usage](#usage)
• [Standalone](#standalone)
• [Claude Desktop Integration](#claude-desktop-integration)
• [Other MCP Hosts](#other-mcp-hosts)
• [Docker Usage](#docker-usage)
• [Architecture](#architecture)
• [pwntools Tools](#pwntools-tools)
• [EDB Plugin Mapping](#edb-plugin-mapping)
• [Binary Ninja Integration](#binary-ninja-integration)
• [Ghidra Integration](#ghidra-integration)
• [Web UI](#web-ui)
• [CTF Examples](#ctf-examples)
• [x64dbg Integration](#x64dbg-integration)
• [IDA Pro Integration](#ida-pro-integration)
• [VS Code Extension](#vs-code-extension)
• [Project Structure](#project-structure)
• [Tool Reference](#tool-reference-26-tools)
• [License](#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

Click to expand the pwntools tool overview (50 tools)

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

| Tool | Description | |------|-------------| | pwntools_analyze_elf | Full ELF binary analysis (headers, sections, symbols, security, strings) | | pwntools_asm | Assemble assembly instructions to bytes (Keystone) | | pwntools_build_rop_chain | Build a ROP chain with ordered gadgets | | pwntools_checksec | Check ELF binary security properties (RELRO, Canary, NX, PIE) | | pwntools_constgrep | Search pwntools/ELF constants by name or value | | pwntools_cyclic | Generate De Bruijn cyclic pattern for offset discovery | | pwntools_cyclic_find | Find offset of a value in cyclic pattern | | pwntools_disasm | Disassemble raw bytes with pwntools (architecture-aware) | | pwntools_elf_deps | Show shared library dependencies and interpreter | | pwntools_elf_patch | Patch bytes in ELF binary at file offset (creates .bak) | | pwntools_elf_read | Read bytes from ELF binary at section or address | | pwntools_elf_sections | List all sections with type, flags, address, size | | pwntools_elf_search | Search ELF binary for byte pattern grouped by section | | pwntools_elf_strings | Extract printable strings from ELF (by section or all) | | pwntools_elf_symbols | Search symbols by regex with address table | | pwntools_enc | Encode shellcode (alphanumeric, nullfree, xor) | | pwntools_entropy | Shannon entropy analysis of file or region | | pwntools_erope | Search ROP gadgets grouped by type (syscall, stackpivot, call, jump) | | pwntools_find_rop | Search for ROP gadgets by regex | | pwntools_flat | Pack values/addresses into flat payload bytes | | pwntools_fmtstr_payload | Generate format string write payload | | pwntools_hexdump | Hex dump with ASCII side (colored, offset-labeled) | | pwntools_make_elf | Compile assembly code into ELF binary | | pwntools_pack | Pack integer to bytes (little/big endian, 8/16/32/64-bit) | | pwntools_shellcraft | Generate shellcode for a given arch/OS (execve, bind/rev shell, etc.) | | pwntools_sigreturn | Generate SROP (Sigreturn-Oriented Programming) frame | | pwntools_unpack | Unpack bytes to integer |

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

EDB Plugin Mapping

Click to expand the EDB plugin coverage table (22 plugins)

| Plugin | MCP Coverage | |--------|-------------| | DebuggerCore | Execution, stepping, breakpoints, registers, memory, state | | BreakpointManager | edbsetbreakpoint, edblistbreakpoints, edbexport/import | | HardwareBreakpoints | edbsethardwarebreakpoint, edbsetwatchpoint | | InstructionInspector | edbinstructiondetail | | Assembler | edbassemble (Keystone optional) | | BinaryInfo | edbgetbinaryinfo | | BinarySearcher | edbsearchmemory | | Backtrace | edbgetbacktrace | | FasLoader | edbloadsymbolfile | | DumpState | edbdumpstate | | FunctionFinder | edblistfunctions | | OpcodeSearcher | edbsearchinstructions | | References | edbfindreferences, edbstringreferences | | ROPTool | edbfindropgadgets | | HeapAnalyzer | edbanalyzeheap | | Analyzer | edbanalyzeregion, edbanalyzebasicblocks | | SymbolViewer | edblookupsymbol | | ProcessProperties | edbgetprocessproperties | | ODbgRegisterView | edbgetregisters, edbgetfpustate, edbgetsimdstate | | Bookmarks | edbaddbookmark, edblistbookmarks, edbremovebookmark | | CheckVersion | Automatically handled | | DebuggerErrorConsole | edbsetdebug_output |

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 serve

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [oakkaya](https://github.com/oakkaya)
- **Source:** [oakkaya/edb-debugger-mcp](https://github.com/oakkaya/edb-debugger-mcp)
- **License:** MIT
- **Homepage:** https://pypi.org/project/edb-debugger-mcp/

Install and usage instructions live in the source repository linked above.