optical-read-mcp

Your agent reads files as text. That's expensive. Show it a picture instead.

Loading a big file into an agent burns thousands of tokens — most of them spent on whitespace and boilerplate the model barely needs at full fidelity. But a model doesn't have to read text. Show it an image of the file and it reads with its vision encoder instead, where a single token is worth roughly ten text tokens.

optical-read-mcp is a small MCP server that does exactly that. Hand it a path; it hands back a dense, line-numbered picture of the file; and a high-resolution vision model — Claude Fable 5, Opus 4.8, Sonnet 5, GPT-5.6 Sol — reads roughly 7× more code per token.

The trick isn't mine. It's DeepSeek-OCR's contexts optical compression, popularized by Sean Goedecke's write-up. This just points it at the thing agents do all day long: reading files.

The gist

- Read("app/router.py")          →  ~8,000 tokens of text in your context
+ ReadMassive("app/router.py")   →  one small PNG the model reads for ~1,100

Same shape as the Read tool you already use — a path, or a list of paths. What comes back is a picture the model treats as the file's actual contents, line numbers and all.

Related MCP server: image-tiler-mcp-server

Use it in Claude Code

The repo ships a project .mcp.json, so it's two steps:

uv sync

Open the folder in Claude Code, approve the optical-read server when it asks (/mcp to check), and you're set. Ask it to read something big and it'll reach for ReadMassive on its own.

Any other MCP client:

{
  "mcpServers": {
    "optical-read": {
      "command": "uv",
      "args": ["run", "optical-read-mcp"]
    }
  }
}

What the picture looks like

Text is packed edge-to-edge into a square — no wasted margins — and every source line is written as ¶N│code:

Blank lines are dropped; a jump in the numbers (12 → 15) brings them back. Nothing is lost — the exact source is recoverable, and the test suite checks that on every run. Full spec in docs/FORMAT.md.

One rule makes or breaks this: pages stay square and under 1560px. Vision pipelines quietly downscale anything larger, and that downscale smears a 5px glyph into mush. Keep both sides small and the model reads it crisp and native.

Does it really save 10×?

No, and it won't pretend to. DeepSeek's headline number is measured inside its own OCR encoder. What you actually save depends on how your reading model counts image tokens, so every read reports the real figure:

On a small file it's a loss — the image has a fixed overhead a few hundred tokens can't beat — and the tool says so and points you back to plain Read. This earns its keep on large files, and on reading a whole pile of them at once.

The three tools

• ReadMassive(paths) — the main event. One path or many, cached by mtime, rendered in parallel.

• ReadMassiveText(text) — same idea for a blob you already have in hand: a giant tool output, pasted logs, a fetched doc.

• ReadMassiveEstimate(paths) — just the token and cost math, no pixels, for when you'd rather decide before committing the context.

Under the hood

Pure Python: Pillow for the rendering, the official MCP SDK for the server. A monospace font is bundled, so it renders identically on macOS, Linux and Windows with nothing to install. The whole thing is four small files, and the tuning knobs live at the top of render.py.

src/optical_read_mcp/
  server.py   the MCP tools
  render.py   text → packed, square, line-numbered PNG   ← the interesting bit
  tokens.py   per-model token & dollar math
  fonts.py    finding a monospace font, anywhere

uv run --with pytest pytest runs the tests; CONTRIBUTING.md covers the rest.

Credits

Standing on the shoulders of:

• DeepSeek-OCR — Contexts Optical Compression

• Sean Goedecke — Should LLMs just treat text content as an image?

• George Mandis — speeding up audio to pay OpenAI less, the same idea in a different key

Built by hyprcat · MIT