Skip to main content
Glama
quickstraw

vision-helper-mcp-server

by quickstraw
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
imageYesImage to analyze: URL, file path, data URI, raw base64, or an array of these.
modelNoOpenRouter model ID, e.g. 'qwen/qwen3.8-max'. Defaults to OPENROUTER_MODEL, then a built-in default; see vision_helper_list_models for options.
quickNoSet true for a fast, cheap analysis: quick model (OPENROUTER_QUICK_MODEL), ~1024-token output, minimal reasoning. Good for yes/no checks, captions, object checks, or brief comparisons (up to 5 images).
promptNoOptional instruction for the vision model, e.g. 'Transcribe all text in this screenshot'. When omitted, a general detailed description is used.
max_tokensNoMaximum number of tokens for the vision model's answer.
temperatureNoSampling temperature (0-2). Lower is more deterministic.

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses behavior beyond annotations: high reasoning effort, high-quality model, automatic retry and fallback, quick mode with ~1024-token output, supported image formats, up to 5 images for comparison, and truncation at 25000 characters. These traits are not present in the annotations, which only declare read-only, open-world, idempotent, non-destructive hints. No contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three paragraphs, each serving a purpose: purpose/usage, default vs quick mode, and input formats/limits. Front-loaded with the core action and usage. No filler words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given six parameters and no output schema, the description covers all essential aspects: input types, model selection (default and quick), prompt customization, token limits, truncation, and retries/fallback. The output type is clarified as text. Sibling tools are checkable via vision_helper_list_models. Nothing critical is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema provides 100% description coverage for all six parameters, so baseline is 3. The description adds value by specifying image file types (PNG, JPEG, WebP, GIF), clarifying array usage for comparison (state the comparison in the prompt), and explaining quick mode behavior. This goes beyond the schema's generic descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a clear verb-resource pair: 'Analyze one or more images with a vision-capable model on OpenRouter and return the analysis as text.' It distinguishes itself from siblings (list_models, check_config) by the task type and explicitly states when to use it: 'whenever you need to know what is in an image.'

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides clear usage context: 'Use this whenever you need to know what is in an image but you cannot see it yourself.' It also offers conditional guidance for quick mode vs default mode, specifying examples like yes/no, captions, or object checks. It doesn't explicitly mention sibling alternatives or when not to use, but the context is sufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly and idempotent, so safety is covered. The description adds useful details: it reports the API key status (masked), model selection, and limits, giving insight into the output and behavior beyond the annotations. It doesn't describe the return format, but the key masking and reporting specifics add transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, consisting of two clear sentences. It provides essential information without unnecessary elaboration, and the key details (what it reports, masking) are front-loaded. Every word contributes to the tool's clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers purpose, usage trigger, and key output details (reports, masks key, lists models/limits). It doesn't describe the exact return format, but for a simple config check, this is likely sufficient. The tool is well-contextualized within the sibling set.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has no parameters, so the input schema is fully covered (100% coverage). The description does not add parameter-related information, but none is needed. Baseline score of 3 is appropriate given no parameters exist.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'Diagnose' and clearly identifies the resource as 'vision analysis configuration problems'. It unambiguously states the tool's purpose and differentiates it from the sibling tools through its action and scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use the tool: 'Run this when analysis fails with a missing-key or configuration error.' This provides clear usage context and indicates the tool is for troubleshooting, even without referencing alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of models to return.
offsetNoNumber of models to skip, for pagination.
searchNoCase-insensitive substring filter on model ID or name, e.g. 'gemini', 'qwen', 'gpt'.

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotation already covers read-only, idempotent, non-destructive behavior, so little additional safety disclosure is needed. The description adds useful behavioral context about the live nature of OpenRouter availability and what the result contains: model IDs, context length, and input price.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the main purpose and organized into clear functions: what the tool lists, when to use it, how to narrow/paginate, and what is returned. It is efficient but slightly repeats the picking-a-model idea across the first two clauses.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Since there is no output schema, the description usefully specifies the return contents: model IDs, context length, and input price. Combined with the annotations, it gives an agent everything needed to select and invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema coverage is 100%, so the schema already documents limit, offset, and search well. The description adds a small amount of practical guidance about search and pagination, but does not materially extend the schema's meaning beyond paging and search usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States the exact action: list vision-capable models currently available on OpenRouter. Purpose is further clarified with concrete use cases, such as finding a valid model ID when a configured model fails, and the resource is clearly distinct from the sibling analyze_image and check_config tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Clearly says when to use the tool: when a configured model fails, when asked what models are available, or when choosing a model for image analysis. It gives practical navigation guidance via search and pagination, though it does not explicitly name alternatives or state when NOT to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 2 tool updatesv1.3.0
    • Changedvision_helper_analyze_image5 fields changed
      • changedInput schema / properties / image / anyOf
        Previous value: -[
-  {
-    "description": "A single image. Accepted forms: an http(s) URL, a local file path, a file:// URI, a data: URI (data:image/png;base64,...), or a raw base64 string.",
-    "minLength": 1,
-    "type": "string"
-  },
-  {
-    "description": "Multiple images (up to 5) analyzed together, e.g. to compare screenshots.",
-    "items": {
-      "minLength": 1,
-      "type": "string"
-    },
-    "maxItems": 5,
-    "minItems": 1,
-    "type": "array"
-  }
-]New value: +[
+  {
+    "description": "A single image: http(s) URL, local file path, file:// URI, data: URI, or raw base64.",
+    "minLength": 1,
+    "type": "string"
+  },
+  {
+    "description": "Multiple images (up to 5) analyzed together for comparison.",
+    "items": {
+      "minLength": 1,
+      "type": "string"
+    },
+    "maxItems": 5,
+    "minItems": 1,
+    "type": "array"
+  }
+]
      • changedInput schema / properties / image / description
        Previous value: -"Image to analyze: a URL, local file path, data URI, raw base64, or an array of these."New value: +"Image to analyze: URL, file path, data URI, raw base64, or an array of these."
      • changedInput schema / properties / model / description
        Previous value: -"OpenRouter model ID to use for vision analysis, e.g. 'google/gemini-3.6-flash'. Defaults to the OPENROUTER_MODEL environment variable, then to a built-in default. Use vision_helper_list_models to discover current vision-capable models."New value: +"OpenRouter model ID, e.g. 'qwen/qwen3.8-max'. Defaults to OPENROUTER_MODEL, then a built-in default; see vision_helper_list_models for options."
      • changedInput schema / properties / prompt / description
        Previous value: -"Optional instruction for the vision model describing what to look for. Example: 'Transcribe all text in this screenshot'. When omitted, a general detailed description is used."New value: +"Optional instruction for the vision model, e.g. 'Transcribe all text in this screenshot'. When omitted, a general detailed description is used."
      • addedInput schema / properties / quick
        Added value: +{
+  "description": "Set true for a fast, cheap analysis: quick model (OPENROUTER_QUICK_MODEL), ~1024-token output, minimal reasoning. Good for yes/no checks, captions, object checks, or brief comparisons (up to 5 images).",
+  "type": "boolean"
+}
    • Changedvision_helper_list_models1 field changed
      • removedInput schema / properties / response_format
        Removed value: -{
-  "default": "markdown",
-  "description": "Output format: 'markdown' for a readable list or 'json' for machine-readable data.",
-  "enum": [
-    "markdown",
-    "json"
-  ],
-  "type": "string"
-}
  2. 3 tool updatesv1.0.0
    • First observedvision_helper_analyze_image
    • First observedvision_helper_check_config
    • First observedvision_helper_list_models
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.5/5.0
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

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • llm-vision-mcp

    ghbalf
    A
    license
    Not graded
    quality
    C
    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.
    1,060
    10
    MIT

  • vision-mcp

    menoxz
    A
    license
    Not graded
    quality
    C
    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

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/quickstraw/vision-helper-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server