OpenImageDebugger MCP
The oid-mcp MCP server: an agent sees image buffers in a live gdb or lldb session, reads values and dumps them to .npy.
- 251 ★ on the repository
- Last commit
Extended access
Why this level
- Exposes the debuggee memory to local processes and writes `.npy` files to disk.
Install
- Works in
Manual install
claude mcp add oid -- uv run --directory /path/to/OpenImageDebugger/resources/oidmcp oid-mcpNeeds a built OpenImageDebugger and `OID_AGENT=1`.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Exposes the debuggee memory to local processes and writes `.npy` files to disk.
This is third-party code. Review the repository files before installing.
What it does
OpenImageDebugger is a gdb and lldb plugin for Linux, with experimental macOS support, that shows images from the memory of the program being debugged. The `oid-mcp` package gives an AI agent eyes on those buffers: it lists observable symbols at a breakpoint, returns renderings and statistics, exact numbers and lossless copies. Tools: `list_sessions`, `list_buffers`, `view` (a PNG rendering with a zoom region), `stats` (per-channel min, max, mean and deviation, NaN and Inf counts), `values` (exact values, up to 1024 per call), `dump` (a `.npy` copy into the user directory), `plot` (a mirror in the human viewer window), `set_view` and `get_view`. A pair of pieces works together: the in-debugger endpoint starts with `OID_AGENT=1` and writes a discovery file with a port and a random token, and `oid-mcp` reads it and does the heavy work outside the fragile debugger process.
Who it is for. C++ and computer vision developers who debug images and matrices in gdb or lldb and want an agent to look at them itself.
Good fit when
- At a breakpoint the agent lists buffers and shows an image with the region of interest.
- You need to check whether a channel has NaN and Inf values and what their range is.
- Exact pixels from an 8 by 8 region are read as numbers for comparison with expectations.
- A buffer is saved to `.npy` for analysis in Python.
Not a fit when
- The debugger has no embedded Python or OpenImageDebugger is not installed.
- Debugging runs on a shared server where program memory must not be exposed to local processes.
- Stable behavior is needed, while the feature is experimental and may change.
Example request
At the breakpoint show the image buffer, find NaN in it and save it to npy for analysis.MCP
- Transport
- stdio
- Authentication
- not required
Environment variables
OID_AGENTrequired- A value of 1 enables the agent endpoint in the debugger.
OID_MCP_MAX_BYTES- Transfer cap for one buffer.
Limitations
The feature is experimental: the protocol and tool set may change without notice. It is enabled by `OID_AGENT=1` and exposes the debuggee memory to local processes, so use it only in trusted local development. It needs a built OpenImageDebugger with `oid.py`, gdb or Homebrew lldb on macOS and `uv`. While the debuggee is running a buffer is unavailable, so stop at a breakpoint. The buffer transfer cap is changed with `OID_MCP_MAX_BYTES`.
How to disable. Remove `OID_AGENT=1` from the debugger environment and delete the oid entry from the MCP configuration. Discovery files live in a private user directory and are overwritten on new sessions.
FAQ
How do I connect oid-mcp to Claude Code?
Run `claude mcp add oid -- uv run --directory /path/to/OpenImageDebugger/resources/oidmcp oid-mcp`. For Cursor add the same entry to `mcp.json` with an absolute path to `uv`, because GUI editors do not inherit PATH.
How does the server find the debugger session?
The in-debugger endpoint writes a discovery file with host, port and token into a private directory. `oid-mcp` reads the same directory, so both processes must be able to see it.
What does the `dump` tool do?
Saves a buffer losslessly as `.npy` into the user dump directory. The `path` parameter is a file name inside that directory, and overwriting requires `overwrite`.
Why do I get a message that the debuggee is running?
Buffers are read only at a stop. Pause at a breakpoint or step and repeat the call.
What if a buffer is too large?
Raise `OID_MCP_MAX_BYTES` if a larger transfer is acceptable, or request a smaller area through `region`.
Discussion
No questions or reviews yet.
Related
MCP serversA debugger MCP server: the agent sets breakpoints, steps through code and reads variables of a live program over DAP.
A transparent proxy between an AI client and an MCP server: shows every JSON-RPC frame in the terminal, checks a capture in CI and exports spans
A debugger with no IDE: an agent sets breakpoints, steps through code and inspects variables in ten languages
An MCP server for the Node.js debugger: breakpoints, stepping, variable inspection and expression evaluation at a pause
A command-line debugger for MCP servers from Giant Swarm: a REPL for tools, OAuth 2.1 and an MCP server mode for Cursor
MCP Server for WinDbg
MCP Server for WinDbg Crash Analysis
An MCP server that hands the agent the Windows debuggers: crash dump analysis, remote and kernel debugging in natural language
README in short
The `oid-mcp` package lives in `resources/oidmcp` of the OpenImageDebugger repository and runs through `uv`. The description has sections on deployment, tools and troubleshooting.