Vision Helper MCP Server

An MCP server that adds vision capability to any LLM. Models that cannot see images (the text-only LLM driving your MCP client) call vision_helper_analyze_image, and this server forwards the image to a vision-capable model on OpenRouter, then returns the analysis as text.

Requirements

• Node.js 18+ (tested on 22)
• An OpenRouter API key (sk-or-v1-...)

Install

npm install -g vision-helper-mcp-server

This installs the vision-helper-mcp command globally (the compiled dist is the only published content). Quick check:

vision-helper-mcp --help

Development / from source

git clone https://github.com/<you>/vision-helper-mcp-server.git
cd vision-helper-mcp-server
npm install
npm run build
node dist\index.js --help

Configuration

The API key and options are resolved, in priority order:

1. Process environment variables — set in your MCP client's env/environment config (recommended; this is also where OPENROUTER_MODEL usually lives).
2. Windows user environment variables — read directly from the registry (HKCU\Environment), i.e. what setx writes. This matters: GUI apps (VS Code, Kilo, Claude Desktop, ...) do not re-read user env vars changed after they were launched, so a key set with setx after launching the client would otherwise be invisible. The server reads the registry itself (re-read on a short refresh cycle), so setx values work with no client restart.
3. Windows system environment variables — registry HKLM\SYSTEM\...\Session Manager\Environment.

On non-Windows platforms only step 1 applies.

| Variable | Purpose | Default | |---|---|---| | OPENROUTER_API_KEY | OpenRouter API key (required for analysis) | — | | OPENROUTER_MODEL | Default vision model ID | qwen/qwen3.8-max | | OPENROUTER_FALLBACK_MODEL | Fallback model tried automatically when the primary model's provider is busy or fails | google/gemini-3.7-flash | | OPENROUTER_QUICK_MODEL | Default model when quick: true is passed to vision_helper_analyze_image | meta/muse-glimmer-30b | | MAX_IMAGE_SIZE | Max image payload bytes | 10485760 (10 MB) | | OPENROUTER_TIMEOUT_MS | Per-request timeout | 120000 (120 s) |

The model can also be chosen per call via the model argument of vision_helper_analyze_image, overriding the environment default.

Kilo (VS Code extension) configuration

Add this server as its own MCP entry. This example appends a vision-helper entry to the mcp object in your Kilo config file (e.g. ~/.config/kilo/kilo.json on Windows):

"vision-helper": {
  "type": "local",
  "command": ["vision-helper-mcp"],
  "enabled": true,
  "timeout": 120000,
  "environment": {
    "OPENROUTER_MODEL": "qwen/qwen3.8-max"
  }
}

OPENROUTER_API_KEY is optional here: if the key is set as a Windows user environment variable (setx OPENROUTER_API_KEY sk-or-v1-...), the server picks it up automatically by reading the registry — no client restart needed. Add the key to the environment block only if you want it explicit in the config.

Claude Desktop / other clients

{
  "mcpServers": {
    "vision-helper": {
      "command": "vision-helper-mcp",
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-...",
        "OPENROUTER_MODEL": "qwen/qwen3.8-max"
      }
    }
  }
}

Tools

This server exposes its tools under its own vision_helper_* names.

vision_helper_analyze_image

Analyze one or more images with an OpenRouter vision model.

| Argument | Type | Description | |---|---|---| | image | string \| string[] | Required. An http(s) URL, local file path, file:// URI, data: URI, or raw base64 string. Pass an array (up to 5) to analyze several images together, e.g. to compare screenshots. Only PNG, JPEG, WebP, and GIF are accepted (the formats OpenRouter supports for vision input); relative file paths resolve against the server's working directory, so prefer absolute paths or URLs. | | prompt | string | Optional instruction, e.g. "Transcribe all text in this screenshot". Defaults to a general detailed description. | | model | string | OpenRouter model ID, e.g. qwen/qwen3.8-max. Defaults to OPENROUTER_MODEL, then to the built-in default. | | max_tokens | number | Max tokens for the answer (64–16000). | | temperature | number | Sampling temperature (0–2). | | quick | boolean | Set true for a fast, cheap analysis — a yes/no, a short caption, an object/color check, or a quick comparison of several images (array, up to 5). Uses OPENROUTER_QUICK_MODEL (default meta/muse-glimmer-30b), caps output at 1024 tokens, and forces minimal reasoning. |

If the model's provider is busy or a request fails transiently (HTTP 429, 5xx, timeout, or network error), the server automatically retries with the OPENROUTER_FALLBACK_MODEL model (google/gemini-3.7-flash by default) so the analysis does not fail. This fallback applies to the default detailed mode (quick: true does not fall back). The response header shows which model actually answered and notes when a fallback was used.

Examples of things to ask your assistant:

• "What is in this image? https://example.com/photo.jpg"
• "Analyze the screenshot at C:\Users\me\Pictures\shot.png"
• "Compare these two images: img1.png and img2.png" (pass an array)
• "Read the text from this image and list the objects: "

Detailed vs quick analysis

vision_helper_analyze_image runs in two modes:

| Need | Mode | |---|---| | Detailed, thorough understanding — transcribe all text, describe objects/people/layout, reason about complex content, or compare several images at once | default | | A fast, cheap, concise answer — a yes/no, a short caption, an object/color check, "is this blurry?", or a high-volume/time-sensitive check (multiple images allowed, up to 5) | quick: true |

Prefer the default mode when completeness, precision, or detail matters more than speed (it can take an array of up to 5 images to compare). Prefer quick: true when latency and cost matter more than detail and a concise read is enough.

vision_helper_list_models

List vision-capable models currently on OpenRouter (filtered to image-input models) so you or the user can pick one. Arguments: search (substring on ID/name, e.g. gemini, qwen, claude), limit (default 25), offset.

vision_helper_check_config

Diagnose setup: shows whether an API key was found, which source it came from (client env / Windows user vars / Windows system vars), the default model, and the size/time limits. The key is always masked (e.g. sk-or-…40a0).

Reliability notes

• The server starts even when no key is configured; key resolution is lazy, so a key set with setx works without restarting anything.
• Chat-completion requests retry up to 3 times on 429 / 5xx / network errors, honoring Retry-After when present (capped at 15 s). If a model's provider is still busy after retries, vision_helper_analyze_image automatically falls back (in the default detailed mode) to the OPENROUTER_FALLBACK_MODEL model (google/gemini-3.7-flash by default) before giving up.
• Image downloads are streamed with a hard byte cap and a 30 s timeout; MIME type is sniffed from magic bytes, so raw base64 payloads need no explicit type. Only the formats OpenRouter supports for vision input are accepted: PNG, JPEG, WebP, GIF (others are rejected with conversion guidance before anything is uploaded).
• Remote image URLs are validated before fetching: redirects are followed manually (max 3 hops) and every hop must be a public http(s) host — private, loopback, link-local, and unresolved hosts are refused.
• The model catalog used by vision_helper_list_models is cached in-process for 10 minutes.
• Errors returned to the model are actionable: invalid key (401), insufficient credits (402), unknown model (404, with a hint to call vision_helper_list_models), rate limit (429), oversized images (with the exact limit), and unsupported formats.

Troubleshooting

| Symptom | Fix | |---|---| | vision_helper_analyze_image returns "No OpenRouter API key found" | Run vision_helper_check_config. Set the key in the client's environment, or setx OPENROUTER_API_KEY sk-or-v1-... and start the client fresh. | | "resolved from: Windows user environment variables" but the key is stale | Registry values are re-read on a short refresh cycle (about once a minute), so an updated setx is picked up without restarting the client or server. | | "Error: Model not found on OpenRouter (HTTP 404)" | The model ID is invalid, renamed, or deprecated. Run vision_helper_list_models and pass a current ID via the model argument. | | "Error: Insufficient OpenRouter credits (HTTP 402)" | Add credits at https://openrouter.ai/settings/credits. | | "Image is N bytes, which exceeds MAX_IMAGE_SIZE" | Shrink/compress the image, or raise MAX_IMAGE_SIZE (cap 50 MB). | | "The N images total X bytes, exceeding the aggregate limit" | Analyzes are capped at 25 MB total across all images per request — split into multiple calls. | | "OpenRouter vision models only accept PNG, JPEG, WebP, or GIF" | Convert the image (e.g. to PNG/JPEG) and retry — these are the formats OpenRouter supports for vision input. | | "Error: OpenRouter rate limit or quota exceeded (HTTP 429)" | Wait a moment and retry; the server already retries transient 429s automatically. | | HTTP 400 on a valid image | Some models accept fewer formats — try qwen/qwen3.8-max or openai/gpt-5 family, or convert the image to PNG/JPEG. |

Security

• The API key is only sent to OpenRouter over HTTPS; it is never logged, and vision_helper_check_config reports only a masked prefix.
• Keys are read from environment variables / the registry — never from files in this repository.
• The analysis tool reads local files only when explicitly requested, validates remote URLs against private/internal hosts, and only ever uploads image content in the four formats OpenRouter accepts.

License

MIT