Skip to main content
Glama
GDB Lite MCP

GDB Lite MCP

by Mort2000

GDB Lite MCP

A small TypeScript MCP server for driving GDB sessions from LLM agents.

GDB Lite MCP intentionally exposes only a thin set of primitives around native GDB. Agents can spawn sessions, execute GDB commands, interrupt hung programs, and close sessions while still using normal GDB features such as breakpoints, watchpoints, command lists, Python snippets, core files, attach, and remote targets.

Requirements

  • Node.js 20 or newer

  • GDB available on PATH

  • A native compiler such as gcc if you want to build the repository scenarios

Related MCP server: gdb and rr Debugging

Install

npm install
npm run build

Run the server locally:

npm start

The package also exposes a gdb-lite-mcp binary after it has been built.

The npm package is intentionally limited to the runtime server, debug guide, and debugging Skill. The eval/scenarios/ directory contains repository development assets; clone this repository if you want to run them locally.

MCP Configuration

Point your MCP client at the published package via npx:

{
  "mcpServers": {
    "gdb-lite": {
      "command": "npx",
      "args": ["-y", "gdb-lite-mcp"]
    }
  }
}

For repository-local evaluation, eval/run_eval.py writes a temporary opencode.json that starts the same server from the built dist/index.js.

Runtime environment variables:

  • GDB_LITE_GDB_PATH: GDB executable path. Defaults to gdb.

  • GDB_LITE_MAX_SESSIONS: maximum live sessions. Defaults to 8; must be a positive integer.

  • GDB_LITE_MAX_INTERNAL_BUFFER_CHARS: per-session retained output buffer. Defaults to 4194304; must be a positive integer.

  • GDB_LITE_AUTO_INIT: set to 0, false, no, or off to disable automatic startup defaults.

Invalid runtime configuration values fail fast when the server starts.

Tools

The server registers these MCP tools:

Tool

Purpose

gdb_spawn

Start a GDB session for a local program, core file, attached PID, or remote target.

gdb_exec

Send a native GDB command, poll output with an empty command, or list sessions with an empty or unknown session_id.

gdb_interrupt

Send SIGINT and wait for GDB to return to a prompt.

gdb_close

Terminate and remove a GDB session, or return the current session list when session_id is unknown.

gdb_exec and gdb_interrupt return structured state such as completion_reason (completed, timeout, or exited), at_prompt, command_pending, needs_interrupt, timed_out, truncated, and byte counts. Use this metadata to avoid stacking commands behind a still-running inferior. Calls on the same session are not queued; concurrent gdb_exec or gdb_interrupt requests are rejected.

The server also exposes a gdb-lite://debug-guide resource backed by GUIDE.md.

Example Workflow

gdb_spawn({
  "prog_path": "bin/program",
  "work_dir": "/absolute/path/to/debug-workspace"
})

gdb_exec({
  "session_id": "...",
  "command": "break main\nrun\nbt\ninfo locals",
  "timeout": 5
})

gdb_close({
  "session_id": "..."
})

Prefer batching related GDB commands in one tool call. For hangs, let the run time out, call gdb_interrupt, then inspect bt, info threads, and relevant locals before continuing.

Debugging Skill

The skills/gdb-debugging directory contains an agent Skill with focused debugging workflows for:

  • crashes

  • hangs

  • memory corruption

  • recursion issues

  • wrong results

  • GDB Python probes

Agents that support repository-local Skills should read skills/gdb-debugging/SKILL.md before using the MCP tools.

Scenarios

The repository eval/scenarios directory contains small native debugging tasks used to evaluate the MCP server and Skill. It is not included in the npm package.

Build all scenario binaries:

python3 eval/scenarios/build_scenarios.py

Each scenario writes local build artifacts under eval/scenarios/<name>/build/, which is ignored by Git.

Evaluation

Repository-local evaluation prompts and config live under eval/. They are not included in the npm package.

npm run build
python3 eval/run_eval.py --scenario hang-tokenizer

Run outputs are written under eval/runs/, which is ignored because it is a local evaluation result artifact.

Development

npm run build
npm test

Generated artifacts such as dist/, node_modules/, scenario build directories, logs, and local evaluation results are ignored by Git.

License

MIT. See LICENSE.

Available Tools

4 tools
gdb_closeClose gdbC

Terminate and remove a gdb session.

Inputs: session_id (required). Returns: closed, existed

gdb_execExecute gdb commandB

Send a gdb command and return all output since the previous gdb_exec or gdb_interrupt call. Empty command only polls output.

Inputs: session_id (required), timeout, max_output_bytes, command. Returns: output, completion_reason, saw_prompt, timed_out, +9 more

gdb_interruptInterrupt gdbB

Send SIGINT to the gdb session/debuggee, wait for the GDB prompt, and return incremental output.

Inputs: session_id (required), timeout, max_output_bytes. Returns: output, completion_reason, saw_prompt, timed_out, +10 more

gdb_spawnSpawn gdbA

Start a gdb session and return a session id. Supports local programs, core files, attach, remote targets, and extra native gdb args.

Inputs: work_dir (required), prog_path, environments, core_path, +3 more. Returns: session_id

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a distinct role: spawning, executing commands, interrupting, and closing sessions. There is no overlap or ambiguity between them.

    Naming Consistency5/5

    All tools follow a consistent 'gdb_' prefix with a clear verb (spawn, exec, interrupt, close), making the naming pattern predictable and understandable.

    Tool Count4/5

    With only 4 tools, the set is minimal but covers the core operations for managing a GDB session. It could benefit from additional tools like session listing, but is reasonable for a 'lite' implementation.

    Completeness4/5

    The tools cover the essential lifecycle of a GDB session: start, execute commands, send interrupts, and close. Minor gaps like session listing are acceptable for a lite MCP.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that provides programmatic access to the GNU Debugger (GDB), enabling AI models to interact with GDB through natural language for debugging tasks.
      9
      Apache 2.0
    • A
      license
      A
      quality
      D
      maintenance
      MCP server that exposes GDB debugging as tools. An AI assistant can set breakpoints, run programs, step through code, inspect variables and memory, and examine registers — all via structured tool calls. Reverse debugging with rr is also supported.
      34
      3
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that enables AI assistants to control GDB debugging sessions, including breakpoint management, thread analysis, and variable inspection, using the GDB/MI protocol.
      22
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that exposes LLDB debugging capabilities, enabling AI-assisted interactive debugging of C/C++ applications through 40 specialized tools.
      29 PyPI
      4
      MIT