🖼️ 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.

Why not vision LLM guess?

Typical vision path	Image Reader MCP
"Describe this image"	Return filename, mime, dimensions, and structured metadata
Paraphrased OCR	Optional Tesseract lines with bounding boxes and confidence
GPS and EXIF leak into context	GPS redacted; trust warnings for suspicious metadata
No provenance	Agent Media Twin JSON with measurable, citeable fields
Cloud API by default	Local-first — sharp + exifr on your machine
Ship and pray	23 unit tests on schema, metadata, OCR hooks, safety limits, doctor, and release gate

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

Tool	Use it when the agent needs to...
read_image	Read a local image and return dimensions, mime, metadata, optional OCR, and trust warnings.

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)

Channel	Status
Glama MCP directory	Listed — claim server for full discoverability
Official MCP Registry	Listed — io.github.SylphxAI/image-reader-mcp @ v0.1.0
TensorBlock MCP Index PR #1113	Open — multimedia/document processing listing
MCP servers community issue #4500	Open — community server highlight
mcp.so listing issue #3068	Open — directory submission request
mcpservers.org submit	Not listed yet — free web-form submission

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

License

MIT © SylphxAI