OpenImageDebugger MCP — Claude Code MCP server: image debugging
Gives AI agents access to image buffers in a live gdb or lldb session via OpenImageDebugger — shows pixels at a breakpoint, returns renderings and stats.
MIT ★ 251 updated 2026-10-23
claude mcp add oid-mcp -- uvx oid-mcpWhat OpenImageDebugger MCP does
Two cooperating parts: an in-debugger endpoint (oid.py with OID_AGENT=1 set) writes a discovery file holding host, port, and token; oid-mcp reads it, connects, and handles the heavy work outside the fragile debugger process — decoding, PNG rendering, statistics, .npy dumps. Tools operate at a breakpoint: list_buffers() enumerates observable buffers, view("frame") shows the whole buffer or a region by coordinates, stats("frame") computes min, max, mean, standard deviation, and NaN count, values("frame", x=100, y=100, w=4, h=4) returns exact numbers for a tiny crop, dump("frame") saves lossless .npy, plot("frame") mirrors the buffer into the viewer window.
Requires a built OpenImageDebugger with deployed oid.py, a debugger with embedded Python (gdb or Homebrew lldb on macOS), and the uv package manager. Both components must read the same discovery directory: ~/.oid-agent/ by default, changeable via OID_AGENT_DIR in both environments. If you run several debug sessions at once, each tool accepts a session=<pid> parameter to pick the right one. The feature is experimental and the protocol may shift; enable it only in trusted local development.
What it helps with
- Check pixel values of a buffer at a breakpoint without copying to console
- Get image channel statistics (min, max, NaN count) inside the debugger
- Dump a buffer from debuggee memory into
.npyfor analysis - Show the agent a rendered fragment of a matrix by coordinates
- Give AI access to an image open in the OID viewer without a debugger
Example prompts for the agent
- Show me the
framebuffer visible in the debugger right now - Compute stats for the
image_databuffer at the current breakpoint - Dump the
matrixbuffer to.npyand save it in./debug_dumps/
How to install OpenImageDebugger MCP
Platform CLI
claude mcp add oid-mcp -- uvx oid-mcpuvx runs the command named after the package; if the README names another one, use uvx --from oid-mcp <command>
Platform CLI
codex mcp add oidmcp -- uvx oid-mcpuvx runs the command named after the package; if the README names another one, use uvx --from oid-mcp <command>
Config file
{
"mcpServers": {
"oidmcp": {
"command": "uvx",
"args": [
"oid-mcp"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from oid-mcp <command>
Config file
{
"servers": {
"oidmcp": {
"type": "stdio",
"command": "uvx",
"args": [
"oid-mcp"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from oid-mcp <command>
Platform CLI
gemini mcp add oidmcp uvx oid-mcpuvx runs the command named after the package; if the README names another one, use uvx --from oid-mcp <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about OpenImageDebugger MCP
How to install OpenImageDebugger MCP in Claude Code?
Run claude mcp add oid-mcp -- uvx oid-mcp in a terminal, or add an entry in .mcp.json with command uvx and argument oid-mcp.
What does OpenImageDebugger MCP do?
Connects an AI agent to image buffers in a live gdb or lldb session: the agent sees a list of buffers, gets renderings, channel statistics, exact pixel values, and dumps .npy files for offline analysis.
What does OpenImageDebugger MCP need to work?
A built OpenImageDebugger with deployed oid.py, a debugger with Python (gdb or Homebrew lldb), the uv package manager, and the OID_AGENT=1 flag when launching the debugger. The debugger and MCP server must read the same discovery directory.