io.github.daedalus/mcp-gdbserver

Start gdbserver to debug a program remotely on TCP port. This tool spawns a new gdbserver process that listens on the specified host and port, ready for a GDB client to connect. The session can then be used for breakpoint management, execution control, and inspection. Args: params (StartGdbserverInput): Validated input parameters containing: - host (str): Host to listen on, default 'localhost' - port (int): TCP port between 1024-65535, default 2345 - program (Optional[str]): Path to executable to debug - args (Optional[list[str]]): Program arguments Returns: str: JSON-formatted string containing session information: Success response: { "session_id": str, # Session ID (e.g., "session_1") "status": str, # "running" or "exited" "host": str, # Host address "port": int, # TCP port "program": str, # Path to executable or null "gdbserver_pid": int # PID of gdbserver process } Error response: "Error: <error message>" Examples: - Use when: "Start debugging /path/to/myapp on port 3333" -> params with port=3333, program="/path/to/myapp" - Use when: "Start gdbserver on port 4444" -> params with port=4444 - Don't use when: Need to attach to running process (use gdbserver_attach instead) - Don't use when: Need multi-process mode (use gdbserver_start_multi instead)

Start gdbserver in multi-process mode. In multi-process mode, gdbserver can debug multiple programs in the same session without exiting when one program finishes. Use this when you need to debug several processes sequentially. Args: params (StartGdbserverMultiInput): Validated input parameters containing: - host (str): Host to listen on - port (int): TCP port between 1024-65535 Returns: str: JSON-formatted string containing session information: Success response: { "session_id": str, "status": str, "host": str, "port": int, "gdbserver_pid": int } Error response: "Error: <error message>" Examples: - Use when: "Start multi-process gdbserver on port 4444" -> params with port=4444 - Don't use when: Need to debug single program (use gdbserver_start instead)

Attach gdbserver to a running process. This tool spawns gdbserver and attaches it to an existing process by PID. You can then connect with GDB to debug the running process. Args: params (AttachToProcessInput): Validated input parameters containing: - pid (int): Process ID to attach to (must be >= 1) - host (str): Host to listen on - port (int): TCP port between 1024-65535 Returns: str: JSON-formatted string containing session information: Success response: { "session_id": str, "status": str, "host": str, "port": int, "gdbserver_pid": int } Error response: "Error: <error message>" Examples: - Use when: "Attach to process 12345 on port 3456" -> params with pid=12345, port=3456 - Don't use when: Need to start new program (use gdbserver_start instead)

List all active debugging sessions. This tool returns information about all current gdbserver sessions that are being managed by this MCP server. Returns: str: JSON-formatted string containing session list: Success response: [ { "session_id": str, "status": str, "host": str, "port": int, "program": str, "gdbserver_pid": int } ] Error response: "Error: <error message>" Examples: - Use when: "What sessions are running?" -> no params needed

Stop a debugging session and terminate gdbserver. This tool stops the specified gdbserver session and terminates the gdbserver process. The session will no longer be available. Args: params (SessionIdInput): Validated input parameters containing: - session_id (str): ID of session to stop Returns: str: JSON-formatted string: Success response: {"session_id": str, "status": "stopped"} Error response: "Error: Session not found. Please check the session_id is correct." Examples: - Use when: "Stop session session_1" -> params with session_id="session_1"

Set a breakpoint at the specified location. This tool connects to the gdbserver session and sets a breakpoint at the specified location using GDB/MI protocol. Args: params (SetBreakpointInput): Validated input parameters containing: - session_id (str): ID of the debugging session - location (str): Breakpoint location (function, file:line, or *address) - condition (Optional[str]): Optional condition Returns: str: JSON-formatted string containing breakpoint information: Success response: { "location": str, "result": dict # GDB breakpoint-insert result } Error response: "Error: <error message>" Examples: - Use when: "Set breakpoint at main" -> params with location="main" - Use when: "Set breakpoint at line 42 in foo.c" -> params with location="foo.c:42" - Use when: "Set breakpoint at address 0x400520" -> params with location="*0x400520" - Use when: "Set conditional breakpoint at main when x > 5" -> params with location="main", condition="x > 5"

Delete a breakpoint by ID. This tool removes a previously set breakpoint from the debug session. Args: params (DeleteBreakpointInput): Validated input parameters containing: - session_id (str): ID of the debugging session - breakpoint_id (int): ID of breakpoint to delete Returns: str: JSON-formatted string: Success response: {"breakpoint_id": int, "deleted": true} Error response: "Error: <error message>" Examples: - Use when: "Delete breakpoint 1" -> params with breakpoint_id=1

Continue execution of the debugged program. This tool sends the continue command to the debugged program, allowing it to run until a breakpoint is hit or the program exits. Args: params (SessionIdInput): Validated input parameters containing: - session_id (str): ID of the debugging session Returns: str: JSON-formatted string containing GDB result: Success response: {"result": str} Error response: "Error: <error message>" Examples: - Use when: "Continue execution of session_1" -> params with session_id="session_1"

Step one instruction (stepping into function calls). This tool executes a single instruction, stepping into any function calls encountered. Args: params (SessionIdInput): Validated input parameters containing: - session_id (str): ID of the debugging session Returns: str: JSON-formatted string containing GDB result: Error response: "Error: <error message>" Examples: - Use when: "Step one instruction" -> params with session_id="session_1"

Execute one instruction (skipping function calls). This tool executes a single instruction, but does not step into function calls - they execute as a single unit. Args: params (SessionIdInput): Validated input parameters containing: - session_id (str): ID of the debugging session Returns: str: JSON-formatted string containing GDB result: Error response: "Error: <error message>" Examples: - Use when: "Step over one instruction" -> params with session_id="session_1"

Interrupt executing program. This tool sends an interrupt signal to the debugged program, causing it to stop at the current instruction. Args: params (SessionIdInput): Validated input parameters containing: - session_id (str): ID of the debugging session Returns: str: JSON-formatted string containing GDB result: Error response: "Error: <error message>" Examples: - Use when: "Stop the running program" -> params with session_id="session_1"

Get stack frames from the debugged program. This tool retrieves the call stack frames, showing the execution path to the current location. Args: params (StackFramesInput): Validated input parameters containing: - session_id (str): ID of the debugging session - max_depth (int): Maximum frames to retrieve (1-100, default 10) Returns: str: JSON-formatted string containing stack frame information: Error response: "Error: <error message>" Examples: - Use when: "Show call stack" -> params with session_id="session_1"

Get local variables in current frame. This tool retrieves all local variables in the current stack frame along with their values. Args: params (GetLocalVariablesInput): Validated input parameters containing: - session_id (str): ID of the debugging session Returns: str: JSON-formatted string containing variable information: Error response: "Error: <error message>" Examples: - Use when: "Show local variables" -> params with session_id="session_1"

List all threads in the debugged program. This tool retrieves information about all threads running in the debugged process. Args: params (SessionIdInput): Validated input parameters containing: - session_id (str): ID of the debugging session Returns: str: JSON-formatted string containing thread information: Error response: "Error: <error message>" Examples: - Use when: "Show all threads" -> params with session_id="session_1"

Select a thread to debug. This tool switches the current context to the specified thread. Args: params (SelectThreadInput): Validated input parameters containing: - session_id (str): ID of the debugging session - thread_id (int): Thread ID to select Returns: str: JSON-formatted string containing result: Error response: "Error: <error message>" Examples: - Use when: "Switch to thread 2" -> params with thread_id=2

Read register values. This tool reads the values of CPU registers. If no specific register is provided, it reads all registers. Args: params (ReadRegisterInput): Validated input parameters containing: - session_id (str): ID of the debugging session - reg (Optional[str]): Register name (e.g., 'rax', 'rip') Returns: str: JSON-formatted string containing register values: Error response: "Error: <error message>" Examples: - Use when: "Read all registers" -> params with reg=None - Use when: "Read RIP register" -> params with reg="rip"

Read memory from the debugged program. This tool reads raw memory from the debugged process at the specified address. Args: params (ReadMemoryInput): Validated input parameters containing: - session_id (str): ID of the debugging session - address (str): Memory address (e.g., '0x400520') - offset (int): Byte offset from address (default 0) - length (int): Bytes to read (1-1024, default 64) Returns: str: JSON-formatted string containing memory contents: Error response: "Error: <error message>" Examples: - Use when: "Read 64 bytes from 0x600a00" -> params with address="0x600a00" - Use when: "Read 16 bytes from variable address" -> params with address="&buffer", length=16

Evaluate an expression in the current context. This tool evaluates a C/C++ expression using the current program state, allowing you to call functions, perform arithmetic, and inspect variables. Args: params (EvaluateExpressionInput): Validated input parameters containing: - session_id (str): ID of the debugging session - expression (str): Expression to evaluate Returns: str: JSON-formatted string containing result: Error response: "Error: <error message>" Examples: - Use when: "What is x + 5?" -> params with expression="x + 5" - Use when: "Get string length" -> params with expression="strlen(buffer)" - Use when: "Call a function" -> params with expression="my_function(arg)"

Load a symbol file for debugging. This tool loads symbols from an executable file for debugging. Args: params (LoadSymbolsInput): Validated input parameters containing: - session_id (str): ID of the debugging session - file (str): Path to executable with symbols Returns: str: JSON-formatted string containing result: Error response: "Error: <error message>" Examples: - Use when: "Load symbols from /path/to/app" -> params with file="/path/to/app"