This MCP server provides an API to discover and attach to local GDB processes and perform common debugging actions through the Model Context Protocol. It exposes a set of tools that let an AI agent or other clients find running GDB sessions, attach to them, and issue commands or inspect state. Key capabilities include discovering GDB processes, attaching to a chosen process, executing arbitrary GDB commands, managing breakpoints, stepping, inspecting memory and registers, retrieving stack traces and locals, disassembling code, and connecting to remote targets. The modular design enables AI-powered debugging workflows where responses are structured and can be fed back into automation pipelines.

To use the server, start it with the MCP configuration described in mcp_config, then connect via the MCP client interface. Typical usage involves first calling sys_find_gdb_processes to enumerate targets, then sys_attach_to_gdb to attach to a specific process. Once attached, use gdb_execute_command and related gdb_* helpers (gdb_set_breakpoint, gdb_delete_breakpoint, gdb_step, gdb_next, gdb_finish, gdb_continue, gdb_get_registers, gdb_examine_memory, gdb_get_stack, gdb_get_locals, gdb_disassemble, gdb_connect_remote) to perform debugging operations. The server is designed to handle blocking GDB commands gracefully, including automatic interrupt signaling when appropriate, to keep the AI agent's interactions responsive.

Prerequisites:

• Python 3.8+ installed on your system
• Git to clone the repository
• Internet access to install Python dependencies

Step-by-step:

1. Clone the repository git clone https://github.com/yywz1999/gdb-mcp-server.git cd gdb-mcp-server

2. Create and (optional) activate a virtual environment python3 -m venv venv source venv/bin/activate # macOS/Linux

   On Windows: .\venv\Scripts\activate

3. Install dependencies python3 -m pip install -r requirements.txt

4. Start the MCP server python3 mcp_server.py

5. Verify the server is running (optional) Ensure there are no port binding errors and the server starts listening for MCP clients.

Notes:

• If you need a different entry point structure, you can adjust the command in mcp_config to point to the appropriate module or script that starts the server.

Tips and considerations:

• The server is designed for development use and may require tuning for production workloads.
• Ensure Python dependencies in requirements.txt are compatible with your Python installation.
• If you encounter issues attaching to GDB, verify you have permission to access GDB processes and that your environment supports the GDB interaction method used (pexpect on Linux, AppleScript/iterm2 on macOS).
• When using remote debugging (gdb_connect_remote), make sure the target is reachable from the host running the MCP server and that any necessary port mappings are configured.
• The MCP tools listed (e.g., gdb_set_breakpoint, gdb_get_registers, gdb_examine_memory) are designed to be composable for AI-driven debugging workflows; consider chaining commands to build higher-level debugging strategies.
• If you plan to integrate with an AI assistant, ensure your MCP client handles structured responses and error cases returned by the server.