Zero-config in one line

npx -y @sylphx/iris

No API key. No global install. Starts a stdio MCP server agents can spawn immediately.

Why Iris feels unfairly good

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

Five reasons teams pick Iris

1. Zero-config MCP — real one-liner for agents.
2. Facts over captions — measurable fields agents can defend.
3. Local-first — geometry/OCR/layout without default cloud VLM.
4. Fail closed — missing native binary does not silently invent an engine.
5. Family ready — compose with Citra (PDF), Cue (video), Locus (code).

What agents get

Primary surface centers on read_image (Agent Media Twin). Optional advanced paths stay evidence-shaped.

Minimal call:

{ "path": "/absolute/path/to/photo.jpg" }

Flagship use cases

1. Screenshots & UI captures — dimensions, text regions, layout without VLM paraphrase
2. Document photos — OCR lines with geometry for citation
3. Trust / privacy — EXIF/GPS handling and trust warnings when requested

Product docs

See objects (L2, optional)

With a local Florence-class sidecar or Ollama, the same read_image can return open-vocab objects with pixel bboxes and scores:

{ "path": "/abs/photo.jpg", "include_semantics": true, "semantics_prompt": "people and animals" }

Objects are scored_non_locator evidence — deterministic L0/L1 facts (geometry/OCR/layout) stay authoritative and always on.

Read images (not vague vision)

Iris is local-first: geometry + OCR + layout blocks + agent_map so a text-only agent can understand picture architecture without a vision model.

Spec: docs/specs/agent-image-read-contract.md

Local-first frontier: Rust decode, Tesseract native layout (no npm ML), optional Ollama VLM; cloud URL optional. Zero API key. Optional L2 local semantics (include_semantics) detects open-vocab objects (people/animals/things) with pixel bboxes via an official Florence-class sidecar (examples/florence-sidecar/) or Ollama -- never authority over OCR/layout locators.

See it work

Why Iris wins for agents

1. Zero-config — npx -y @sylphx/iris starts MCP on stdio.
2. Facts over captions — structure agents can cite, not free-text “I see a chart”.
3. Local-first — files never leave the machine by default.
4. Family — pair with Citra (PDF), Cue (video), Locus (code).

MCP Tool Surface

Supported formats: PNG, JPEG, GIF, WebP, TIFF, and other formats the Rust decode engine supports (optional sharp covers additional formats when installed).

Quick Start

Claude Code

Claude Desktop

Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "iris": {
      "command": "npx",
      "args": ["-y", "@sylphx/iris"]
    }
  }
}

Any MCP Client

npx -y @sylphx/iris

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