Vision MCP Server

A small, production-shaped Model Context Protocol (MCP) server that gives any MCP client (Claude Desktop / Code, etc.) multimodal vision tools — describe, OCR, visual Q&A, object detection — backed by any vision model via OpenRouter.

Built to be governed by default: every tool instructs the model to abstain ("cannot determine from image") rather than guess — the same source-over-derived discipline I apply across my AI automation work.

Pluggable backend — swap providers/models without touching tool logic. Ships with a real OpenRouter backend (standard-library only, no HTTP dependency) and a deterministic Mock backend for offline demos and tests.
Runs offline for inspection — the tool logic is verifiable with zero dependencies and no API key.

Tools

Tool	What it does
`describe_image`	Concise or full description of an image
`extract_text`	OCR-style verbatim text extraction
`ask_image`	Visual question answering (abstains when unsupported)
`detect_items`	Lists distinct objects/items (optionally scoped to categories)

Images are accepted as a local path, an http(s) URL, or a data: URI.

Quickstart

Offline — zero dependencies, no key:

python3 examples/offline_demo.py
python3 -m unittest discover -s tests -q

As a real MCP server:

pip install -r requirements.txt        # installs the `mcp` SDK
export OPENROUTER_API_KEY=sk-...
python -m vision_mcp.server             # stdio MCP server

Then register it in your MCP client. Env: VISION_MCP_MOCK=1 runs without a key; VISION_MCP_MODEL picks the model.

Architecture

flowchart LR
  C["MCP client<br/>(Claude, etc.)"] -->|stdio / MCP| S["Vision MCP Server<br/>(FastMCP)"]
  S --> T["Tools<br/>describe · extract · ask · detect"]
  T --> BE["VisionBackend<br/>(pluggable)"]
  BE --> M["Mock<br/>(offline)"]
  BE --> O["OpenRouter<br/>(any vision model)"]
  classDef gov fill:#e9ecff,stroke:#5560aa,color:#222;
  class T gov;

See docs/design.md for the design rationale.

About

Gerardo Dellán — AI Transformation & Automation Program Manager. I lead AI programs and build them hands-on. linkedin.com/in/gerry-df · more patterns: agentic-automation-patterns

License

MIT — see LICENSE.