# OpenImageDebugger MCP

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.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 251 repo stars
- Author: OpenImageDebugger
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/OpenImageDebugger/OpenImageDebugger/tree/HEAD/resources/oidmcp
- Updated: 2026-10-23
- Security check: automated, 2026-11-16 (text) — warning: a command downloads a script from astral.sh and runs it right away. Do not run such commands without an explicit yes from the human.
- HTML: https://affpapa.org/en/nevibecode/mcp/openimagedebugger-mcp

## What it 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.

## Requirements
- Needs: Python and uv (commands run via uvx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add oid-mcp -- uvx oid-mcp
```
uvx runs the command named after the package; if the README names another one, use uvx --from oid-mcp <command>

### Codex

**Platform CLI**
```bash
codex mcp add oidmcp -- uvx oid-mcp
```
uvx runs the command named after the package; if the README names another one, use uvx --from oid-mcp <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add oidmcp uvx oid-mcp
```
uvx runs the command named after the package; if the README names another one, use uvx --from oid-mcp <command>

## When to use it
- 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 `.npy` for 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
- Show me the `frame` buffer visible in the debugger right now
- Compute stats for the `image_data` buffer at the current breakpoint
- Dump the `matrix` buffer to `.npy` and save it in `./debug_dumps/`

## Similar
- [discover-debugging](https://affpapa.org/en/nevibecode/skills/discover-debugging.md) — skill · 104 installs
- [lldb](https://affpapa.org/en/nevibecode/skills/lldb.md) — skill · 761 installs
- [zig-debugging](https://affpapa.org/en/nevibecode/skills/zig-debugging.md) — skill · 590 installs
- [dbg](https://affpapa.org/en/nevibecode/skills/dbg.md) — skill · 674 installs
- [cli-anything-lldb](https://affpapa.org/en/nevibecode/skills/cli-anything-lldb.md) — skill · 467 installs
- [scikit-image](https://affpapa.org/en/nevibecode/rules/scikit-image.md) — rule · ★ 3589 repo stars

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
