de en es ja ko ru zh

OpenRouter MCP Multimodal Server

Name: OpenRouter MCP Multimodal Server
Author: stabgan

by stabgan

Overview Schema Source Related Servers Discussions Admin

TypeScript

Hybrid

Access 300+ LLMs — Claude, Gemini, GPT, Llama, Qwen, Grok, and more — through OpenRouter via the Model Context Protocol. Analyze images, audio, and video. Generate images, speech, music, and video (Veo 3.1, Sora 2 Pro, Seedance, Wan). Chat with any model. Works with Claude Desktop, Cursor, Kiro, VS Code, Windsurf, Cline, and any MCP-compatible client. Every tool returns structured _meta.code errors so MCP clients can switch on failure modes without parsing strings.

One-Click Install

After clicking, the target client opens a confirmation prompt. You'll need to paste your OPENROUTER_API_KEY — the deeplink ships a placeholder so no secrets end up in shared links.

Related MCP server: OpenRouter MCP Multimodal Server

Why This One?

Feature	Status
Text chat with 300+ models	✅
Image analysis (vision)	✅ Native with sharp optimization
Audio analysis	✅ Transcription + analysis, base64 auto-encoded
Audio generation	✅ Conversational, speech, and music with format auto-detection
Image generation	✅ Path-sandboxed disk output
Video understanding	✅ v3 — mp4, mpeg, mov, webm from files, URLs, or data URLs
Video generation	✅ v3 — Veo 3.1 / Sora 2 Pro / Seedance / Wan via async API with progress notifications
Auto image resize + compress	✅ Configurable (defaults 800px max, JPEG 80%)
Model search + validation	✅ Filter by vision / audio / video modality
Free model support	✅ Default: free Nemotron VL
Docker support	✅ Multi-arch (amd64 + arm64), ~345 MB Alpine
Retry-After + jitter	✅ Honors `Retry-After` header, avoids thundering herd
IPv4 + IPv6 SSRF blocklist	✅ Covers mapped, compat, multicast, 6to4, Teredo, ORCHID
Structured error taxonomy	✅ Closed `_meta.code` so clients can switch on failure modes
Reasoning-model awareness	✅ Detects `max_tokens` cutoff during CoT, guides the caller
MCP 2025 tool annotations	✅ `readOnlyHint` / `destructiveHint` / `idempotentHint` on every tool

Tools

Tool	Description
`chat_completion`	Send messages to any OpenRouter model. Detects reasoning-model cutoffs.
`analyze_image`	Analyze images from local files, URLs, or data URIs. Auto-optimized with sharp.
`analyze_audio`	Analyze/transcribe audio (WAV, MP3, FLAC, OGG, etc.) from files, URLs, or data URIs.
`analyze_video`	Analyze/transcribe video (mp4, mpeg, mov, webm) from files, URLs, or data URIs.
`generate_image`	Generate images from text prompts. Supports `aspect_ratio` (14 values), `image_size` (0.5K–4K), and `max_tokens`. Optional path-sandboxed disk save.
`generate_audio`	Generate audio from text. Auto-detects format, wraps raw PCM in WAV.
`generate_video`	Generate video via OpenRouter's async API (Veo 3.1 / Sora 2 Pro / Seedance / Wan). Submits, polls, downloads, saves.
`get_video_status`	Resume polling a `generate_video` job by id. Download + save when complete.
`search_models`	Search/filter models by name, provider, or capabilities (vision / audio / video).
`get_model_info`	Get pricing, context length, and capabilities for any model.
`validate_model`	Check if a model ID exists on OpenRouter.

All error responses carry _meta.code from a closed taxonomy: INVALID_INPUT · UNSAFE_PATH · UPSTREAM_HTTP · UPSTREAM_TIMEOUT · UPSTREAM_REFUSED · UNSUPPORTED_FORMAT · RESOURCE_TOO_LARGE · ZDR_INCOMPATIBLE · MODEL_NOT_FOUND · JOB_FAILED · JOB_STILL_RUNNING · INTERNAL

Quick Start

Prerequisites

Get a free API key from openrouter.ai/keys.

Option 1: npx (no install)

{
  "mcpServers": {
    "openrouter": {
      "command": "npx",
      "args": ["-y", "@stabgan/openrouter-mcp-multimodal"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-..."
      }
    }
  }
}

Option 2: Docker

{
  "mcpServers": {
    "openrouter": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "OPENROUTER_API_KEY=sk-or-v1-...",
        "stabgan/openrouter-mcp-multimodal:latest"
      ]
    }
  }
}

Option 3: Global install

npm install -g @stabgan/openrouter-mcp-multimodal

{
  "mcpServers": {
    "openrouter": {
      "command": "openrouter-multimodal",
      "env": { "OPENROUTER_API_KEY": "sk-or-v1-..." }
    }
  }
}

Option 4: Smithery

npx -y @smithery/cli install @stabgan/openrouter-mcp-multimodal --client claude

Configuration

Variable	Required	Default	Description
`OPENROUTER_API_KEY`	Yes	—	Your OpenRouter API key
`OPENROUTER_DEFAULT_MODEL`	No	`nvidia/nemotron-nano-12b-v2-vl:free`	Default model for chat + analyze tools
`DEFAULT_MODEL`	No	—	Alias for above
`OPENROUTER_MODEL_CACHE_TTL_MS`	No	`3600000`	Model cache TTL (ms)
`OPENROUTER_IMAGE_MAX_DIMENSION`	No	`800`	Longest edge for resize (px)
`OPENROUTER_IMAGE_JPEG_QUALITY`	No	`80`	JPEG quality (1–100)
`OPENROUTER_IMAGE_FETCH_TIMEOUT_MS`	No	`30000`	Image URL timeout
`OPENROUTER_IMAGE_MAX_DOWNLOAD_BYTES`	No	`26214400`	Image URL size cap (~25 MB)
`OPENROUTER_IMAGE_MAX_REDIRECTS`	No	`8`	Image URL redirect cap
`OPENROUTER_IMAGE_MAX_DATA_URL_BYTES`	No	`20971520`	Image data URL size cap (~20 MB)
`OPENROUTER_AUDIO_FETCH_TIMEOUT_MS`	No	`30000`	Audio URL timeout
`OPENROUTER_AUDIO_MAX_DOWNLOAD_BYTES`	No	`26214400`	Audio URL size cap (~25 MB)
`OPENROUTER_AUDIO_MAX_REDIRECTS`	No	`8`	Audio URL redirect cap
`OPENROUTER_AUDIO_MAX_DATA_URL_BYTES`	No	`20971520`	Audio data URL size cap
`OPENROUTER_DEFAULT_VIDEO_MODEL`	No	`google/gemini-2.5-flash`	Default for `analyze_video`
`OPENROUTER_DEFAULT_VIDEO_GEN_MODEL`	No	`google/veo-3.1`	Default for `generate_video`
`OPENROUTER_VIDEO_FETCH_TIMEOUT_MS`	No	`60000`	Video URL timeout
`OPENROUTER_VIDEO_MAX_DOWNLOAD_BYTES`	No	`104857600`	Video URL size cap (~100 MB)
`OPENROUTER_VIDEO_MAX_REDIRECTS`	No	`8`	Video URL redirect cap
`OPENROUTER_VIDEO_MAX_DATA_URL_BYTES`	No	`104857600`	Video data URL size cap
`OPENROUTER_VIDEO_POLL_INTERVAL_MS`	No	`15000`	Async video poll cadence
`OPENROUTER_VIDEO_MAX_WAIT_MS`	No	`600000`	Max wait before returning a resumable handle
`OPENROUTER_VIDEO_GEN_MAX_BYTES`	No	`268435456`	Generated video download cap (~256 MB)
`OPENROUTER_VIDEO_INLINE_MAX_BYTES`	No	`10485760`	Inline video ceiling (~10 MB)
`OPENROUTER_OUTPUT_DIR`	No	`process.cwd()`	Sandbox root for `save_path`
`OPENROUTER_ALLOW_UNSAFE_PATHS`	No	—	`1` disables the sandbox
`OPENROUTER_LOG_LEVEL`	No	`info`	`error` / `warn` / `info` / `debug`

Security notes

Analyze tools can read local files and fetch HTTP(S) URLs. URL fetches block private/link-local/reserved IPv4 and IPv6 targets (SSRF mitigation) and cap response size.
Generate tools write to disk through a path sandbox: save_path is resolved against OPENROUTER_OUTPUT_DIR and any traversal attempt is rejected. Override with OPENROUTER_ALLOW_UNSAFE_PATHS=1.
IPv6 SSRF blocklist covers loopback, unspecified, IPv4-mapped, IPv4-compatible, link-local, site-local, ULA, multicast, documentation, Teredo, ORCHID, and 6to4 of private IPv4.

Usage Examples

# Chat
Use chat_completion to explain quantum computing in simple terms.

# Vision
Use analyze_image on /path/to/photo.jpg and tell me what you see.

# Audio transcription
Use analyze_audio on /path/to/recording.mp3 to transcribe it.

# Video understanding
Use analyze_video on /path/to/clip.mp4 — what happens at 00:15?

# Generate audio
Use generate_audio with prompt "Explain neural networks" and voice "alloy", save to ./response.wav

# Generate music
Use generate_audio with model "google/lyria-3-clip-preview" and prompt "upbeat jazz piano trio"

# Generate image
Use generate_image with prompt "a cat astronaut on mars", aspect_ratio "16:9", image_size "1K", save to ./cat.png

# Generate video
Use generate_video with model "google/veo-3.1", prompt "a calm river at sunrise",
resolution 720p, duration 4, save to ./river.mp4

# Resume a video job
Use get_video_status with video_id "vid_abc123" and save_path "./river.mp4"

Architecture

src/
├── index.ts                    # Entry, env validation, graceful shutdown
├── tool-handlers.ts            # 11 tools (annotated) + dispatch
├── model-cache.ts              # TTL + in-flight coalescing
├── openrouter-api.ts           # REST client (chat + /videos)
├── errors.ts                   # Closed ErrorCode enum
├── logger.ts                   # JSON-line structured logger
└── tool-handlers/
    ├── fetch-utils.ts          # SSRF, bounded fetch, data-URL parser
    ├── openrouter-errors.ts    # SDK/HTTP → ErrorCode classifier
    ├── completion-utils.ts     # Reasoning-model cutoff detection
    ├── path-safety.ts          # save_path sandbox
    ├── chat-completion.ts      # Text + multimodal chat
    ├── analyze-image.ts        # Vision analysis
    ├── analyze-audio.ts        # Audio transcription
    ├── analyze-video.ts        # Video understanding
    ├── generate-image.ts       # Image generation
    ├── generate-audio.ts       # Audio generation + streaming
    ├── generate-video.ts       # Video generation (async)
    ├── image-utils.ts          # Sharp optimization, MIME sniffing
    ├── audio-utils.ts          # Audio format detection
    ├── video-utils.ts          # Video format detection
    ├── search-models.ts        # Model search
    ├── get-model-info.ts       # Model detail lookup
    └── validate-model.ts       # Model existence check

Development

git clone https://github.com/stabgan/openrouter-mcp-multimodal.git
cd openrouter-mcp-multimodal
npm install
cp .env.example .env  # Add your API key
npm run build
npm start

npm test                    # 163 unit tests, <1s
npm run test:integration    # Live API tests
npm run lint
node scripts/live-e2e.mjs  # 16 live E2E scenarios

Upgrading from v2

v3 is additive — no tool schemas or env vars were removed.

Three new tools: analyze_video, generate_video, get_video_status
Structured _meta.code on every error response (text messages preserved)
save_path sandboxed by default — set OPENROUTER_OUTPUT_DIR or OPENROUTER_ALLOW_UNSAFE_PATHS=1
Reasoning-model awareness: content: null + finish_reason: length now returns INVALID_INPUT with a preview instead of empty string
IPv6 SSRF coverage extended to mapped, compat, multicast, 6to4, Teredo, ORCHID

Compatibility

Works with any MCP client: Kiro · Claude Desktop · Cursor · Windsurf · Cline · any MCP-compatible client.

License

MIT

Contributing

Issues and PRs welcome. Please open an issue first for major changes.

Available Tools

11 tools

analyze_audioB

Read-only

Analyze or transcribe an audio file using a multimodal model

ParametersJSON Schema

Name	Required	Description
`model`	No
`question`	No	Question or instruction about the audio (default: transcribe)
`audio_path`	Yes	File path, URL, or data URL (base64-encoded audio)

TDQS

B3.4/5.0

Behavior3/5

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the description adds limited behavioral insight beyond stating 'analyze or transcribe'. It does not disclose limitations like supported formats, file sizes, or any side effects, but there is no contradiction with annotations.

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 a single, concise sentence with no redundant words. It effectively communicates the core function without unnecessary elaboration.

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

Completeness2/5

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

The description does not explain the return format or output structure, and no output schema is provided. It also omits details about supported audio formats, maximum file size, or any behavioral constraints. Given the tool's complexity, this is a significant gap.

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 description adds value for the 'question' parameter by noting an optional instruction with a default of 'transcribe', which is beyond the schema. However, the 'model' parameter lacks any description in the schema and is not addressed in the description. With 67% schema coverage, the description partially compensates.

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 clearly states the tool's purpose: analyzing or transcribing an audio file. It specifies the verb ('analyze or transcribe') and the resource ('audio file'), and the name 'analyze_audio' distinguishes it from sibling tools like 'analyze_image' and 'analyze_video'.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, scenarios where transcription vs. analysis is appropriate, or exclusions. The sibling list includes 'generate_audio' but no context for choosing between them.

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

analyze_imageB

Read-only

Analyze an image using a vision model

ParametersJSON Schema

Name	Required	Description
`model`	No
`question`	No	Question about the image
`image_path`	Yes	File path, URL, or data URL

TDQS

B3.4/5.0

Behavior3/5

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds that it uses a vision model, but does not disclose performance characteristics, required permissions, or output format. It provides minimal behavioral context beyond annotations.

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 a single, front-loaded sentence with no redundancy. Every word contributes to clarity, making it highly efficient.

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

Completeness2/5

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

Given no output schema, the description should hint at the return type (e.g., text, structured data). It also omits limitations like image size or supported formats. The tool is simple, but the description is too sparse for complete understanding.

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?

Schema description coverage is 67% (2 of 3 parameters have descriptions). The tool description adds no additional meaning beyond the schema, so it meets the baseline expectation without improvement.

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 'Analyze an image using a vision model' clearly specifies a verb (analyze) and resource (image), and distinguishes it from sibling tools like analyze_audio and analyze_video.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives such as generate_image or when not to use it. The description lacks any usage context or conditions.

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

analyze_videoA

Read-only

Analyze or transcribe a video file using a multimodal model. Accepts mp4, mpeg, mov, or webm from a local file path, HTTP(S) URL, or base64 data URL. Default model: google/gemini-2.5-flash.

ParametersJSON Schema

Name	Required	Description
`model`	No	Override the model ID.
`question`	No	Question or instruction about the video (default: describe).
`video_path`	Yes	File path, HTTP(S) URL, or base64 data URL. Supported formats: mp4, mpeg, mov, webm.

TDQS

A4/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, indicating a safe read operation. The description adds format details and default model but does not disclose behavioral traits like output format or side effects. Description is consistent with annotations but adds limited value beyond them.

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 concise with two sentences: first stating purpose, second covering formats and default model. No unnecessary information, though the structure could be slightly improved by front-loading the most critical info.

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

Completeness3/5

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

With no output schema, the description should clarify what the tool returns (e.g., transcription or analysis text). It lacks this, and omits guidance on the 'question' parameter's behavior versus the default. Overall, it covers input basics but is incomplete regarding expected output.

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?

Schema coverage is 100% with detailed descriptions for all three parameters. The description adds the default model ('google/gemini-2.5-flash'), which is not in the schema, providing useful context. The rest of the parameter info is already covered by the schema.

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 clearly states the tool analyzes or transcribes a video file using a multimodal model, specifies supported formats (mp4, mpeg, mov, webm), and mentions a default model. This distinguishes it from sibling tools like analyze_audio and analyze_image, which target other modalities.

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?

The description implies usage for video content via the resource name and accepted formats, but does not explicitly state when to use this tool over alternatives or provide exclusions. The context is clear, but guidance is implicit.

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

chat_completionB

Send messages to an OpenRouter model and get a response

ParametersJSON Schema

Name	Required	Description
`model`	No	Model ID (optional, uses default)
`messages`	Yes
`max_tokens`	No
`temperature`	No

TDQS

B3.2/5.0

Behavior2/5

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false. The description adds no extra behavioral context such as token consumption, cost, or response format. For a mutation tool, this is insufficient transparency.

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 a single, clear sentence with no extraneous information. It is front-loaded with the core action, but could benefit from mentioning key parameters.

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

Completeness2/5

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

The tool has multiple parameters and nested objects, but the description omits details on response format, error handling, streaming, or any limitations. Without an output schema, the description should provide more context to be complete.

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

Parameters2/5

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

Schema coverage is low (25%), and the description does not explain individual parameters like temperature or max_tokens. It only implies 'model' and 'messages' are used. The description fails to compensate for the schema's lack of detail.

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 clearly states the verb 'Send messages' and the resource 'OpenRouter model', directly conveying the tool's function. It distinguishes from sibling tools like analyze_audio or generate_image, which have different modalities.

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

Usage Guidelines3/5

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

No explicit guidance on when or when not to use this tool versus alternatives. The verb 'chat' implies it is for conversational interactions, but no mention of situations where other tools (e.g., analyze_image) would be more appropriate.

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

generate_audioA

Generate audio from a text prompt. Conversational models (e.g. openai/gpt-audio) respond in spoken audio. Music models (e.g. google/lyria-3-clip-preview) need a structured prompt. Output format is auto-detected and file extension is corrected automatically.

ParametersJSON Schema

Name	Required	Description
`model`	No	Model ID (default: openai/gpt-audio)
`voice`	No	Voice name (default: alloy)
`format`	No	Requested format: pcm16 (default), mp3, flac, opus
`prompt`	Yes	Text input
`save_path`	No	Optional path to save the audio. Extension auto-corrected and routed through OPENROUTER_OUTPUT_DIR sandbox.

TDQS

A4.2/5.0

Behavior3/5

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

Annotations are minimal (readOnlyHint=false, etc.), and the description adds behavioral info like auto-detection and file extension correction, but does not disclose potential side effects, permissions, or rate limits.

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 concise sentences with no fluff, front-loaded with main purpose, and each sentence adds distinct value.

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?

Given 5 parameters, no output schema, and minimal annotations, the description covers core functionality and parameter nuances well, though could mention what the tool returns (e.g., audio data or saved path).

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?

Schema coverage is 100%, but the description adds context beyond schema: explains prompt structure for music models, notes defaults for model/voice, and describes auto-correction for save_path.

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 clearly states the tool generates audio from text, specifying two model categories (conversational vs music) and auto-detection of output format. It distinguishes between use cases effectively.

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?

Provides guidance on using conversational vs music models and mentions auto-detection of format, but does not explicitly exclude alternatives or compare with sibling tools like analyze_audio.

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

generate_imageA

Generate an image from a text prompt. Optionally conditioned on one or more reference images (file paths, http(s) URLs, or data URLs) for character / style consistency. Sends modalities: ["image","text"] by default; override via the modalities field if needed.

ParametersJSON Schema

Name	Required	Description
`model`	No
`prompt`	Yes
`save_path`	No	Optional path to save the image. Routed through the OPENROUTER_OUTPUT_DIR sandbox.
`image_size`	No	Output resolution bucket. 1K is the default; 0.5K / 2K / 4K are model-dependent.
`max_tokens`	No	Cap on completion tokens. Defaults to the model context window, which can trip free-tier quotas; set e.g. 4096 on low-credit accounts.
`modalities`	No	Override the default `modalities: ["image","text"]` sent to OpenRouter. Most callers should leave this unset. Provide e.g. ["text"] to suppress image output for inspection / captioning.
`aspect_ratio`	No	Output aspect ratio (e.g. 1:1, 16:9, 9:16, 4:3, 3:4, 21:9). Model-dependent.
`input_images`	No	Optional reference images for visual consistency. Each entry may be a local file path (sandboxed to OPENROUTER_INPUT_DIR / OPENROUTER_OUTPUT_DIR / cwd), an http(s) URL, or a `data:image/...;base64,...` URL. Inlined as multimodal user content in the order given.

TDQS

A4.4/5.0

Behavior4/5

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

Discloses default modalities and ability to override, plus reference image formats. Adds context beyond annotations (which are neutral). Could mention non-destructive nature, but not necessary.

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 well-front-loaded sentences with zero waste. Every sentence adds value.

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?

Covers main functionality, conditioning, and modality override. Lacks explicit return format, but 'generate an image' implies output. Adequate for tool complexity.

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?

Adds meaning beyond schema by explaining input_images purpose (character/style consistency) and modalities override. Schema coverage is high, but description provides useful context.

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?

Clearly states it generates an image from a text prompt, with optional conditioning on reference images. Distinct from sibling tools like analyze_audio or chat_completion.

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?

Implies when to use reference images for consistency hints, and mentions modality override. Lacks explicit when-not or alternatives, but sibling tools are clearly different in modality.

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

generate_videoA

Generate a video from a text prompt using an OpenRouter video-generation model (default: google/veo-3.1). Submits an async job, polls until completion or max_wait_ms, then downloads the result. Optionally conditioned on first/last-frame images or reference images. Large outputs are auto-saved when save_path is provided and path-sandboxed.

ParametersJSON Schema

Name	Required	Description
`seed`	No	Deterministic seed when supported.
`model`	No	Override the video model ID.
`prompt`	Yes	Text description of the desired video.
`duration`	No	Duration in seconds (model-dependent).
`provider`	No	Provider-specific passthrough options keyed by provider slug.
`save_path`	No	Where to save the video. Routed through the OPENROUTER_OUTPUT_DIR sandbox; extension auto-corrected.
`resolution`	No	480p / 720p / 1080p / 1K / 2K / 4K (model-dependent).
`max_wait_ms`	No	Total time to wait for the async job before returning a resumable handle (default 600000 ms).
`aspect_ratio`	No	16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 21:9 / 9:21 (model-dependent).
`last_frame_image`	No	Optional image used as the last frame for frame transitions.
`poll_interval_ms`	No	Polling cadence (default 15000 ms).
`reference_images`	No	Optional style/content reference images.
`first_frame_image`	No	Optional image (path, URL, or data URL) used as the first frame for image-to-video.

TDQS

A4.1/5.0

Behavior4/5

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

Beyond the annotations (which are all false), the description discloses async job submission, polling, timeout handling, auto-saving with path sandboxing, and image conditioning. No contradictions with annotations.

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 a single paragraph of four sentences, efficiently covering the main action and key details. It could be slightly more structured with bullet points, but no information is wasted.

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?

Given the tool's complexity (13 parameters, async behavior, optional images, sandboxing), the description covers the essential workflow: async submission, polling, auto-save, and sandbox. It does not explain return values or error handling details, but no output schema exists.

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?

Schema coverage is 100%, but the description adds meaningful context: default model, model-dependent constraints on resolution/duration, and auto-corrected save path extension. This adds value beyond the schema alone.

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 clearly states it generates a video from a text prompt using an OpenRouter model, and it distinguishes itself from sibling tools like generate_audio and generate_image by specifying video generation with async polling and optional image conditioning.

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

Usage Guidelines3/5

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

The description implies usage for video generation but does not explicitly state when to use this tool vs alternatives (e.g., get_video_status for status checks, analyze_video for analysis). No 'when not to use' guidance is provided.

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

get_model_infoC

Read-onlyIdempotent

Get details about a specific model

ParametersJSON Schema

Name	Required	Description	Default
`model`	Yes

TDQS

C2.9/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, which cover the behavioral profile. The description adds no additional behavioral context beyond stating it retrieves details, so it meets the baseline but does not exceed annotations.

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 a single concise sentence with no redundant words. However, it is slightly too brief and could benefit from additional context without becoming verbose.

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

Completeness2/5

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

Given no output schema and a single parameter, the description should at least hint at what kind of details are returned (e.g., capabilities, metadata). The current description is too minimal to fully inform an agent about the tool's output or usage prerequisites.

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

Parameters2/5

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

The input schema has one parameter 'model' with no description, and the tool description does not clarify what the parameter expects (e.g., model name, ID, or exact string). With 0% schema description coverage, the description should compensate but fails to add meaning.

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

Purpose4/5

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

The description clearly states the tool gets details about a specific model, which distinguishes it from siblings like search_models (searching for models) and other generation tools. However, it does not specify what constitutes 'details', leaving some ambiguity.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives like search_models, nor does it mention when to avoid using it. No context or exclusions are given.

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

get_video_statusA

Read-onlyIdempotent

Resume a previously submitted video generation job by id. Returns the latest status; if completed, downloads the video (and saves it when save_path is provided).

ParametersJSON Schema

Name	Required	Description	Default
`video_id`	Yes	Job id from a previous generate_video call.
`save_path`	No	Optional save path (applies when the job is already completed).

TDQS

A4.1/5.0

Behavior4/5

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

Annotations indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds that it returns latest status and downloads the video if completed, which provides behavioral context beyond annotations. 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?

Single sentence, front-loaded with the primary action, no unnecessary words. Every part earns its place.

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

Completeness3/5

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

While the description covers the completion case, it omits what happens when the job is still running (e.g., returns status only). No output schema to supplement, leaving a gap for incomplete jobs.

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 has 100% coverage with descriptions for video_id and save_path. The description reiterates the save_path usage but does not add new semantic value beyond the schema.

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 clearly states the action: 'Resume a previously submitted video generation job by id.' It specifies the resource (video generation job) and distinguishes from siblings like generate_video and analyze_video.

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?

The description implies usage after a generate_video call, but does not explicitly state when not to use it or mention alternatives. It is clear enough for an agent to infer context.

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

search_modelsC

Read-onlyIdempotent

Search available OpenRouter models

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No
`query`	No
`provider`	No
`capabilities`	No

TDQS

C2/5.0

Behavior2/5

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

Annotations already declare the tool as read-only, non-destructive, and idempotent. The description adds no further behavioral context, such as how the search is performed, pagination behavior, or any limitations (e.g., maximum results). With annotations covering safety, the description does not extend transparency beyond what is already inferred.

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

Conciseness2/5

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

The description is extremely concise (one sentence) but lacks substance. While brevity is valued, it omits critical details such as what the search filters are or how results are returned. The single sentence does not fully earn its place as it fails to inform adequate use.

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

Completeness1/5

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

Given the tool has 4 parameters (including a nested object) and no output schema, the description is severely incomplete. It does not clarify the search behavior (e.g., whether 'query' is a free-text search or exact match), the effect of 'provider' and 'capabilities' filters, or the structure of results. An agent cannot reliably invoke this tool based solely on the current description.

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

Parameters1/5

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

Schema description coverage is 0%, so the description must explain the parameters. It does not mention 'query', 'provider', 'capabilities', or 'limit' at all, leaving the agent to infer their meaning from names alone. The nested 'capabilities' object further complicates usage without documentation.

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

Purpose3/5

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

The description 'Search available OpenRouter models' clearly indicates the tool's purpose: searching models on OpenRouter. However, it does not distinguish this from sibling tools like 'get_model_info' or 'validate_model', which also deal with models. A more specific description (e.g., listing all searchable criteria) would improve differentiation.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives such as 'get_model_info' for retrieving a specific model's details. The description offers no context about prerequisites, expected input patterns, or scenarios where search is preferred.

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

validate_modelA

Read-onlyIdempotent

Check if a model ID exists

ParametersJSON Schema

Name	Required	Description	Default
`model`	Yes

TDQS

A3.7/5.0

Behavior3/5

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

Annotations already declare readOnly and idempotent, so description adds no extra behavioral context (e.g., return type for non-existence, error handling). Adequate but no added value beyond annotations.

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?

Single concise sentence, front-loaded with verb and purpose. No redundant words.

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

Completeness3/5

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

Simple tool but absence of output schema means description should clarify return type (e.g., boolean). It doesn't, leaving ambiguity about the response for non-existent models.

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?

With 0% schema description coverage, description adds crucial context that the 'model' parameter is an ID. Still lacks format or validation hints, but compensates partially.

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?

Description clearly states the tool checks existence of a model ID, which is a distinct purpose from siblings like get_model_info (retrieves details) and search_models (lists models).

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

Usage Guidelines2/5

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

No guidance on when to use this vs alternatives (e.g., get_model_info for details, search_models for browsing). Does not specify prerequisites or context.

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.

7 tool updatesv1.8.3May 4, 2026

Addedanalyze_audio
Addedanalyze_video
Addedgenerate_audio

Changedgenerate_image6 fields changed

addedInput schema / properties / aspect_ratio

Added value: +{
+  "description": "Output aspect ratio (e.g. 1:1, 16:9, 9:16, 4:3, 3:4, 21:9). Model-dependent.",
+  "enum": [
+    "1:1",
+    "2:3",
+    "3:2",
+    "3:4",
+    "4:3",
+    "4:5",
+    "5:4",
+    "9:16",
+    "16:9",
+    "21:9",
+    "1:4",
+    "4:1",
+    "1:8",
+    "8:1"
+  ],
+  "type": "string"
+}

addedInput schema / properties / image_size

Added value: +{
+  "description": "Output resolution bucket. 1K is the default; 0.5K / 2K / 4K are model-dependent.",
+  "enum": [
+    "0.5K",
+    "1K",
+    "2K",
+    "4K"
+  ],
+  "type": "string"
+}

addedInput schema / properties / input_images

Added value: +{
+  "description": "Optional reference images for visual consistency. Each entry may be a local file path (sandboxed to OPENROUTER_INPUT_DIR / OPENROUTER_OUTPUT_DIR / cwd), an http(s) URL, or a `data:image/...;base64,...` URL. Inlined as multimodal user content in the order given.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / max_tokens

Added value: +{
+  "description": "Cap on completion tokens. Defaults to the model context window, which can trip free-tier quotas; set e.g. 4096 on low-credit accounts.",
+  "minimum": 1,
+  "type": "number"
+}

addedInput schema / properties / modalities

Added value: +{
+  "description": "Override the default `modalities: [\"image\",\"text\"]` sent to OpenRouter. Most callers should leave this unset. Provide e.g. [\"text\"] to suppress image output for inspection / captioning.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / save_path / description

Added value: +"Optional path to save the image. Routed through the OPENROUTER_OUTPUT_DIR sandbox."

Addedgenerate_video
Addedget_video_status
Changedsearch_models2 fields changed
- addedInput schema / properties / capabilities / properties / audio
```
Added value: +{
+  "type": "boolean"
+}
```
- addedInput schema / properties / capabilities / properties / video
```
Added value: +{
+  "type": "boolean"
+}
```

6 tool updatesv1.8.2Apr 2, 2026
- First observedanalyze_image
- First observedchat_completion
- First observedgenerate_image
- First observedget_model_info
- First observedsearch_models
- First observedvalidate_model

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored 2026-05-04 11:15 across 11 tools

Disambiguation5/5

Each tool targets a distinct function: analyzing audio/image/video, generating content, chat completions, and model queries. No two tools have overlapping purposes, and even the video generation status tool is clearly a helper for async workflows.

Naming Consistency4/5

Most tools follow a verb_noun pattern (analyze_, generate_, get_, search_, validate_). The exception is 'chat_completion', which combines two nouns rather than a verb_noun, causing a minor inconsistency in the naming style.

Tool Count5/5

With 11 tools, the set covers all major modalities (audio, image, video, text) and supporting functions (model info, search, validation). The count is well-balanced—not excessive or too sparse for the server's multimodal purpose.

Completeness4/5

Core analysis, generation, and query tools are present. Some minor gaps exist (e.g., no explicit tool for listing all models, though search_models and get_model_info cover it). Overall, the surface is comprehensive for typical multimodal workflows.

Maintenance

ActivityActive

ResponsivenessSlow

Resources

Need Help?

Related Servers

Related MCP Connectors

APICK AI A
app.apick
LLM chat, text tools, image generation, editing, batch image jobs, and asynchronous video generation
AI & Machine Learning Image & Video Processing
1511
Kaito Query Service
io.github.TheSandemon
AI LLM with Gemini, MiniMax, Replicate, OpenRouter. Vision, search, code review. USDC on Base.
Search Blockchain
2
treg.toOAuth
io.github.superdesigndev
OpenRouter for tools and data. Compare catalog providers and call them from one hosted MCP endpoint.
Agent Orchestration
1709
BrainstormRouter MCP Server
io.github.justinjilg
AI routing, memory, guardrails, and governance. Routes across Claude, GPT, Gemini.
RAG Systems Knowledge & Memory Agent Orchestration
2

Related MCP Servers

OpenRouter MCP Server
Agent Orchestration Autonomous Agents
heltonteixeira
A
license
A
quality
D
maintenance
Provides integration with OpenRouter.ai, allowing access to various AI models through a unified interface.
Updated a year ago (2025-11-08 14:21 UTC)
4
379 npm
63
Apache 2.0
OpenRouter MCP Multimodal
Search Image & Video Processing Multimedia Processing
hoangdn3
F
license
B
quality
D
maintenance
Provides access to OpenRouter.ai's diverse model ecosystem for text chat and image analysis capabilities, with support for multimodal conversations and automatic image optimization.
Updated 10 months ago (2025-12-20 07:07 UTC)
7
12 npm
-
OpenRouter MCP Server
Search
th3nolo
A
license
A
quality
B
maintenance
Provides access to 400+ AI models from OpenRouter, enabling users to chat with models like GPT-4, Claude, Gemini, and Llama, compare responses across multiple models, and retrieve model information with pricing details.
Updated 12 days ago (2026-09-29 07:52 UTC)
4
27 npm
13
MIT
Vision MCP Server
Image & Video Processing Autonomous Agents
TheNomadInOrbit
A
license
B
quality
D
maintenance
Enables vision capabilities for any AI model by routing image analysis requests through OpenRouter's vision models. It provides tools to analyze images from URLs, local file paths, or base64 data.
Updated a year ago (2025-10-09 22:43 UTC)
2
320 npm
20
MIT

One-Click Install

Why This One?

Tools

Quick Start

Prerequisites

Option 1: npx (no install)

Option 2: Docker

Option 3: Global install

Option 4: Smithery

Configuration

Security notes

Usage Examples

Architecture

Development

Upgrading from v2

Compatibility

License

Contributing

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Appeared in Searches