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-...)

Related MCP server: llm-vision-mcp

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.

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.

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:

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

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