Skip to main content
Glama

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

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.

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

Available Tools

3 tools
vision_helper_analyze_imageAnalyze Image (Vision Helper)A
Read-onlyIdempotent

Analyze one or more images with a vision-capable model on OpenRouter and return the analysis as text. Use this whenever you need to know what is in an image but you cannot see it yourself.

Default mode is detailed and thorough (high reasoning effort, high-quality model, automatic retry and fallback). Pass quick: true for a fast, cheap answer (quick model, ~1024-token output, minimal reasoning) — e.g. a yes/no, a caption, or an object check.

Accepts an http(s) URL, local file path, file:// URI, data: URI, or raw base64 (PNG, JPEG, WebP, or GIF only); pass an array of up to 5 to compare images (state the comparison in the prompt). Long analyses are truncated at 25000 characters.

Inputs: image (required), model, quick, prompt, +2 more.

vision_helper_check_configCheck Vision Helper ConfigurationA
Read-onlyIdempotent

Diagnose vision analysis configuration problems. Reports whether the OpenRouter API key is set and where it was loaded from, which models would be used (default, quick, fallback), and the configured size/time limits. The key is only shown masked. Run this when analysis fails with a missing-key or configuration error.

Inputs: no named parameters.

vision_helper_list_modelsList Vision Models (Vision Helper)A
Read-onlyIdempotent

List vision-capable models currently available on OpenRouter, so you or the user can pick one for image analysis. Use it to find a valid model ID (e.g. when a configured model fails) or when asked which models are available. Narrow with 'search' (substring on provider or family, e.g. 'gemini', 'qwen') and paginate with limit/offset. Returns model IDs with context length and input price.

Inputs: limit, offset, search.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: analyze images, list available models, and diagnose configuration issues. There is no overlapping functionality, so an agent can reliably select the correct tool for a given task.

    Naming Consistency5/5

    All tool names follow the same pattern: 'vision_helper_' prefix followed by a verb_noun pair (analyze_image, list_models, check_config). This is perfectly consistent and predictable, making tool selection easy.

    Tool Count5/5

    With only 3 tools, the server is tightly scoped to its purpose—image analysis via OpenRouter—without unnecessary surface area. Each tool is essential to the workflow, and the count is well within the ideal range for a focused utility.

    Completeness5/5

    The toolset covers the full lifecycle of using the server: analyze images (the core action), discover available models (selection), and diagnose configuration problems (troubleshooting). There are no obvious gaps for the stated domain; an agent can perform all necessary operations without dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables any LLM to describe images from file paths, URLs, or base64 data by forwarding them to a supported vision provider such as OpenAI, Anthropic, or local Ollama models.
      10
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for analyzing images using multiple vision LLM providers (OpenCode, OpenAI, Anthropic, Google, and custom OpenAI-compatible endpoints). Provides tools to analyze single or multiple images, list providers, and test vision capabilities.
      MIT