🖼️ Image Reader MCP

Your agent looked at the image. Did it see the truth?

Evidence-first image reading for AI agents. One call turns any local image into an Agent Media Twin — dimensions, metadata, optional OCR with bounding boxes, and trust warnings you can cite without asking a vision LLM to guess.

Local-first · One smart read_image call · Evidence with bbox + provenance · 23 tests

SOTA family roadmap: docs/roadmap/sota-family-roadmap.md.

⭐ Star this repo if agents should read images with facts, not vision-model guesses. · Quick start · See it work · Why not vision LLM guess?

Part of the Sylphx Reader portfolio — orchestration and portfolio ADR live in smart-reader-mcp.

The problem

Images are not filenames. They are pixels, EXIF, orientation, embedded GPS, hidden metadata, and text that only exists if you OCR it with geometry.

Most agent stacks route images through a vision LLM and get a plausible description. Dimensions get rounded. OCR text gets paraphrased. Metadata disappears. Citations become "the model said so." Then the agent hallucinates — confidently.

Image Reader MCP is built for the moment your agent needs measurable facts about an image, not a creative caption.

Related MCP server: Agent Helper

Why not vision LLM guess?

See it work

Install once. Call once.

claude mcp add image-reader -- npx @sylphx/image-reader-mcp

{
  "path": "/absolute/path/to/photo.jpg",
  "include_metadata": true,
  "include_ocr": true
}

read_image inspects the file locally and returns an Agent Media Twin — no generative LLM required:

{
  "filename": "photo.jpg",
  "mime": "image/jpeg",
  "dimensions": { "width": 4032, "height": 3024 },
  "orientation": 1,
  "metadata": {
    "Make": "ExampleCamera",
    "Model": "Pro X",
    "DateTimeOriginal": "2026-03-15T14:22:10"
  },
  "ocr": {
    "available": true,
    "lines": [
      {
        "text": "INVOICE #1042",
        "bbox": { "x": 120, "y": 48, "width": 310, "height": 36 },
        "confidence": 92
      }
    ]
  },
  "trust_warnings": []
}

Abbreviated shape — optional OCR skips gracefully when Tesseract is not installed.

MCP Tool Surface

Supported formats: PNG, JPEG, GIF, WebP, TIFF, and other formats sharp can decode.

Quick Start

Claude Code

claude mcp add image-reader -- npx @sylphx/image-reader-mcp

Claude Desktop

Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "image-reader": {
      "command": "npx",
      "args": ["@sylphx/image-reader-mcp"]
    }
  }
}

Any MCP Client

npx @sylphx/image-reader-mcp

Node.js >=22.13 is required. Optional OCR uses a local Tesseract adapter when installed — no cloud credentials required by default.

Security model

• Local-first — read_image resolves paths on the local machine; no cloud vision API by default.

• GPS redaction — location metadata is stripped from agent-facing output unless explicitly opted in.

• Size and format limits — oversized or unsupported inputs return structured errors, not partial guesses.

• Optional OCR — Tesseract runs locally when installed; missing OCR is reported as available: false, not silent failure.

• Trust warnings — suspicious EXIF, orientation, or metadata anomalies surface in trust_warnings for agent verification.

Release proof

Claims are backed by CI benchmark:release-gate and the shipped-path matrix (Rust-default route, no legacy Node engine on primary tools).

bun run benchmark:release-gate

Artifact: benchmark-artifacts/image_reader_release_gate.json — must report status: passed before release.

Development

git clone https://github.com/SylphxAI/image-reader-mcp.git
cd image-reader-mcp
bun install
bun run build
bun test
bun run doctor
bun run benchmark:release-gate

Useful checks:

bun run check
bun run typecheck
bun run validate
bun run benchmark:release-gate

Example read_image requests live in examples/.

Support

• Issues

• npm package

• Portfolio orchestration: smart-reader-mcp

Help this reach more builders

If vision-model guesses have wasted your context, your citations, or your trust in agent output, you are exactly who this project is for.

⭐ Star the repo — it is the fastest way to help more agent builders find evidence-first image reading. Share it in your MCP client setup, team wiki, or agent stack README.

Discovery (in progress)

Know another MCP directory? Open an issue with the link.

License

MIT © SylphxAI