Skip to main content
Glama
README.md
# vision-mcp

Give a **non-vision coding agent** (OpenCode, Claude Code, Cursor, Cline, …) the ability to
"see" an image — for UI/design review, OCR, "what's on this screenshot", or comparing a
render to an expectation — using **free OpenRouter vision models**.

Zero dependencies. Speaks MCP over stdio. The agent calls one tool:

```
analyze_image(prompt, image)  ->  { content, servedModel, attempts, tried }
```

- `image` = local file path **or** http(s) URL.
- The server converts everything to **base64** (the free nemotron endpoint rejects http image
  URLs but accepts base64), then calls OpenRouter.
- **Model chain:** several free vision models first (each with retries), then a cheap paid
  fallback. First model that answers wins; the result says which one served it.

## Why

Agents without native vision cannot judge whether a game/UI *looks* good. Numeric layout
checks catch clipping, not beauty. This tool lets the agent itself run a **design review** on
Playwright screenshots before shipping — no need to pick a vision *subagent*.

## Models (defaults, override via env)

Free (tried in order, 2 attempts each):
- `nvidia/nemotron-3.5-super-vl:free`
- `google/gemma-4-31b-it:free`
- `nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free`
- `google/gemma-4-26b-a4b-it:free`

Cheap paid fallback (last resort, 3 attempts):
- `z-ai/glm-5.3-flash:floor`

Free endpoints are rate-limited; the paid fallback guarantees an answer. Check current free
models at https://openrouter.ai/models (filter input modality = image, price = 0).

## Install

### Option A — run from source (simplest)

```bash
git clone https://github.com/<you>/vision-mcp
cd vision-mcp
# no npm install needed (zero deps)
export OPENROUTER_API_KEY=sk-or-v1-...
node server.mjs
```

### Option B — MCP client config

OpenCode (`opencode.json` / `opencode.jsonc`):

```jsonc
{
  "mcp": {
    "servers": {
      "vision": {
        "type": "local",
        "command": ["node", "/abs/path/to/vision-mcp/server.mjs"],
        "environment": {
          "OPENROUTER_API_KEY": "sk-or-v1-...",
          "VISION_MODELS": "nvidia/nemotron-3.5-super-vl:free,google/gemma-4-31b-it:free",
          "VISION_PAID_FALLBACK": "z-ai/glm-5.3-flash:floor"
        }
      }
    }
  }
}
```

Claude Desktop / Cursor / Cline use an equivalent `mcpServers` block (command + env).
See `.env.example` for all options.

## Configuration (environment)

| Variable | Default | Meaning |
|---|---|---|
| `OPENROUTER_API_KEY` | — (required) | OpenRouter key |
| `VISION_MODELS` | nemotron,gemma-31b,… | comma-separated free models, in order |
| `VISION_PAID_FALLBACK` | (empty) | one cheap paid model tried last |
| `VISION_ATTEMPTS` | `2` | attempts per free model |
| `VISION_PAID_ATTEMPTS` | `3` | attempts for the paid fallback |
| `VISION_TIMEOUT_MS` | `90000` | per-attempt timeout |
| `VISION_MAX_MB` | `20` | max input image size |
| `VISION_ALLOWED_DIR` | (unset) | if set, local reads confined to this dir (+ OS temp) |
| `OPENROUTER_BASE_URL` | `https://openrouter.ai/api/v1` | API base |

## Security

- The API key is read **only from the environment** — never bundled, never logged.
- If `VISION_ALLOWED_DIR` is unset, the tool can read **any local file path** (it's a local
  dev tool). **Set `VISION_ALLOWED_DIR` to sandbox it** to a screenshots folder if you want
  to restrict reads.
- Images are sent to OpenRouter (the model provider you select). Don't feed secrets/screenshots
  you wouldn't send to a third party.

## Programmatic use (any MCP host)

The tool is standard MCP; the agent writes its own `prompt` per task (e.g. "harsh design
review: layout, hierarchy, biggest problem, polish 1–5"). A ready-made design-review prompt
lives in the Playgama skill (`templates/vision-design-review-prompt.md`).

## License

MIT — see [LICENSE](LICENSE).

TDQS

A4.5/5.0

Scored across 1 tool

Disambiguation5/5

Only one tool exists, so there is no possibility of misselection. Its purpose—answering an arbitrary prompt about an image via a vision model chain—is stated unambiguously, including accepted inputs (path or URL) and return shape.

Naming Consistency4/5

analyze_image follows a clean verb_noun snake_case convention, which is ideal. With a single tool there is no broader pattern to demonstrate consistency against, so it can't quite earn a 5.

Tool Count4/5

A single tool is genuinely sufficient here because the free-form prompt parameter makes it general-purpose (OCR, UI review, render comparison). It is narrowly scoped rather than trivial, though one tool offers no room for specialized conveniences like multi-image diffing.

Completeness4/5

The domain is 'get an answer about an image,' and the tool covers local paths, URLs, retries, and model fallback with diagnostic metadata returned. Minor gaps: no native multi-image/comparison mode and no way to configure or inspect the model chain, but the prompt-driven design lets agents work around these.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues