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.

Built as a more robust replacement for TheNomadInOrbit/Vision-MCP-Server: no build-step assumptions, lazy key resolution, Windows setx-style environment variable support, image format sniffing, request retries, and clear actionable errors.

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, 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 (it does not replace or share tools with any other vision server you have configured). 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": "google/gemini-3.6-flash"
  }
}

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": "google/gemini-3.6-flash"
      }
    }
  }
}

Tools

This server is a standalone MCP server with its own tool names (vision_helper_*), so it can run side by side with other vision MCP servers without tool collisions.

vision_helper_analyze_image

Analyze one or more images with an OpenRouter vision model.

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: "

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, response_format (markdown|json).

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.

• 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