Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-openrouter chat with anthropic/claude-sonnet-4: explain the plot of inception"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
🚀 One MCP server for OpenRouter models 🚀
mcp-openrouter is a Python MCP server that lets Codex, Claude Code, opencode, and other MCP hosts call OpenRouter models from local stdio tools.
It exposes chat, image generation, embeddings, model listing, and model search through a small FastMCP server with retry handling, host-aware installation, and optional default model environment variables.
Install the published server into every detected MCP client:
uvx mcp-openrouter install --yesInstall into selected clients:
uvx mcp-openrouter install --yes --clients codex,claude,opencodeRun from a local checkout:
git clone https://github.com/tsilva/mcp-openrouter.git
cd mcp-openrouter
uv sync --dev
keyenv doctor
keyenv run -- uv run mcp-openroutermcp-openrouter with no arguments starts the stdio server. The explicit command is uv run mcp-openrouter serve.
Related MCP server: Perplexity Ask OpenRouter
uvx mcp-openrouter install --yes # install into detected MCP clients
uvx mcp-openrouter install --yes --force # replace an existing openrouter config
uvx mcp-openrouter uninstall --yes # remove from detected MCP clients
uv run mcp-openrouter # run the local stdio server
uv run pytest tests/test_cli.py tests/test_client.py tests/test_config.py tests/test_installer.py tests/test_release_metadata.py tests/test_server.py
keyenv run -- uv run pytest tests/test_tools.py
uv run ruff check src/
uv run ruff format src/Tool | Purpose |
| Send a prompt or message list to an OpenRouter chat model. |
| Generate one image and optionally save it to an absolute local path. |
| Generate embeddings for a string or list of strings. |
| List models, optionally filtered by |
| Search model names and slugs, returning up to 20 matches. |
Example MCP prompts:
Use openrouter chat with anthropic/claude-sonnet-4 to summarize this file
Use openrouter generate_image with google/gemini-3-pro-image-preview to create a square app icon
Use openrouter embed with mistralai/mistral-embed-2312 to embed "Hello world"
Use openrouter list_models with capability "image_gen"
Use openrouter find_models to search for "claude"OPENROUTER_API_KEY is required for all tool calls. For a local checkout, its .keyenv.toml maps the variable to macOS Keychain: use keyenv set OPENROUTER_API_KEY to replace it, keyenv doctor to verify it, and keyenv run -- ... to launch the server or live tests. Python still reads the value normally from os.environ.
Optional defaults make the model parameter optional for matching tools:
DEFAULT_TEXT_MODEL=google/gemini-3-pro-image-preview
DEFAULT_IMAGE_MODEL=google/gemini-3-pro-image-preview
DEFAULT_CODE_MODEL=anthropic/claude-sonnet-4.5
DEFAULT_VISION_MODEL=google/gemini-3-pro-image-preview
DEFAULT_EMBEDDING_MODEL=mistralai/mistral-embed-2312The current tools read DEFAULT_TEXT_MODEL, DEFAULT_IMAGE_MODEL, and DEFAULT_EMBEDDING_MODEL. DEFAULT_CODE_MODEL and DEFAULT_VISION_MODEL are available for client conventions. Non-secret defaults may remain in .env; the API key must not.
Python 3.10+ is required.
The published runtime command installed into hosts is uvx mcp-openrouter.
Supported installer targets are Codex, Claude Code, and opencode.
generate_image.output_path must be absolute, for example /Users/you/output.png.
Unit tests mock network calls. tests/test_tools.py requires a live OPENROUTER_API_KEY.
After changing server code, restart the MCP host so it launches a fresh server process.
Keep server.json, CHANGELOG.md, and the package version in sync before release. The Makefile release helper is make release-x.y.z.
Register a local checkout when you want an MCP host to run your working tree instead of the published PyPI package.
Claude Code:
claude mcp add openrouter --scope user -- keyenv run --manifest /path/to/mcp-openrouter/.keyenv.toml -- uv run --directory /path/to/mcp-openrouter mcp-openrouterCodex:
codex mcp add openrouter -- keyenv run --manifest /path/to/mcp-openrouter/.keyenv.toml -- uv run --directory /path/to/mcp-openrouter mcp-openrouteropencode:
{
"mcp": {
"openrouter": {
"type": "local",
"command": ["keyenv", "run", "--manifest", "/path/to/mcp-openrouter/.keyenv.toml", "--", "uv", "run", "--directory", "/path/to/mcp-openrouter", "mcp-openrouter"],
"enabled": true
}
}
}
Send a chat completion request to any OpenRouter model.
| Name | Required | Description | Default |
|---|---|---|---|
| seed | No | Random seed for deterministic outputs | |
| stop | No | List of stop sequences | |
| model | No | Model identifier (e.g., "anthropic/claude-sonnet-4", "openai/gpt-4o"). If not specified, uses DEFAULT_TEXT_MODEL environment variable. | |
| top_k | No | Top-k sampling (number of top tokens to consider) | |
| top_p | No | Nucleus sampling threshold 0-1 | |
| prompt | No | User message to send (provide either prompt or messages, not both) | |
| system | No | Optional system prompt to set context | |
| messages | No | Multi-turn conversation as a list of {role, content} dicts (provide either prompt or messages, not both) | |
| provider | No | Provider routing control (e.g., {"order": ["Anthropic", "Google"]}) | |
| json_mode | No | If True, request JSON-formatted response (backward compat) | |
| max_tokens | No | Maximum tokens in response (model default if not specified) | |
| temperature | No | Sampling temperature 0-2 (model default if not specified) | |
| response_format | No | Response format spec, e.g. {"type": "json_schema", ...}. Supersedes json_mode if both provided. | |
| presence_penalty | No | Penalize tokens already present (-2 to 2) | |
| reasoning_effort | No | Reasoning effort level: "minimal", "medium", or "high" | |
| assistant_prefill | No | Text to prefill the assistant response with | |
| frequency_penalty | No | Penalize repeated tokens (-2 to 2) |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for disclosing behavioral traits. It only states the action without explaining rate limits, cost implications, error handling, or output format. The schema adds some detail, but the description itself lacks transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one sentence, front-loaded with the main purpose. It is efficient and to the point, though it could provide a bit more context without becoming overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite a full output schema, the description is too brief for a tool with 17 parameters. It does not explain parameter interplay (e.g., prompt vs messages) or provide context on typical use cases. An agent would benefit from more guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add any parameter-specific meaning beyond what the schema already provides, but it does not need to since the schema is thorough.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Send') and resource ('chat completion request') and mentions 'any OpenRouter model', which clearly distinguishes it from sibling tools like 'embed' or 'generate_image'. It aligns with common terminology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 criteria for selecting it over other tools like 'embed' or 'find_models', nor any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate embeddings for text input using an OpenRouter embedding model.
| Name | Required | Description | Default |
|---|---|---|---|
| input | Yes | Text string or list of strings to embed | |
| model | No | Embedding model (e.g., "mistralai/mistral-embed-2312"). If not specified, uses DEFAULT_EMBEDDING_MODEL environment variable. | |
| dimensions | No | Custom embedding dimensions (model-dependent) | |
| encoding_format | No | Output format: "float" or "base64" (default: float) |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. It does not disclose whether the tool is read-only, has side effects, requires authentication, or any other behavioral traits beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the core purpose. It is concise but lacks structure or additional sections.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and full schema coverage, the description is partially complete. However, it lacks usage guidance and behavioral transparency, which would be needed for an agent to use it confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond the schema's parameter descriptions, but does not detract either.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (generate), the resource (embeddings), the input (text), and the provider (OpenRouter). It is specific and distinguishes from sibling tools like chat, generate_image, and list_models.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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, nor any context about appropriate use cases or preconditions. It only states the function.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for models by name or slug.
| Name | Required | Description | Default |
|---|---|---|---|
| search_term | Yes | Text to search for in model names (e.g., "claude", "gpt", "gemini") |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It only states what it does (search by name or slug) but fails to disclose important behavioral traits such as case sensitivity, partial matching, or whether it returns exact matches only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that is front-loaded and contains no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and an output schema, the description is adequate but lacks behavioral details like whether the search is case-insensitive or returns partial matches. It is minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a description for 'search_term'. The tool description adds the concept of 'slug' which is not in the schema description, providing additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches for models by name or slug, which is a specific verb-resource combination. It implicitly differentiates from sibling 'list_models' that likely lists all models.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need to find a specific model, but it does not explicitly state when to use this tool over alternatives like 'list_models', nor does it provide any when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate an image using an OpenRouter image generation model.
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | Image size - 1K, 2K, or 4K | 1K |
| model | No | Image model (e.g., "google/gemini-3-pro-image-preview"). If not specified, uses DEFAULT_IMAGE_MODEL environment variable. | |
| prompt | Yes | Image description - be specific about style, colors, composition | |
| quality | No | Quality setting (e.g., "high", "medium", "low") | |
| background | No | Background setting (e.g., "transparent" for PNG/WebP) | |
| output_path | No | Optional absolute file path to save the image. Must be an absolute path if provided (e.g., "/Users/name/output.png"). | |
| aspect_ratio | No | Aspect ratio - 1:1, 16:9, 9:16, 4:3, 3:4, or 21:9 | 1:1 |
| output_format | No | Output format (e.g., "png", "webp", "jpeg") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for disclosing behavioral traits. It only states that the tool generates an image via OpenRouter, with no mention of costs, rate limits, authorization, error handling, or potential side effects. This is insufficient for a tool with mutation-like behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the core action. It is concise with no wasted words, though it may be too brief for the complexity of the tool (8 parameters). Overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 8 parameters, no output schema, and no annotations, the description is too brief. It does not explain return values, error behavior, or any contextual details about the generation process. The completeness is lacking for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond the schema; it does not explain parameter interactions or provide usage examples. It neither enhances nor detracts from the schema's clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Generate' and the resource 'image', and specifies the platform 'OpenRouter image generation model'. This differentiates it from sibling tools (chat, embed, find_models, list_models) which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for generating images, but it does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or limitations. The context is clear but lacks explicit usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List available OpenRouter models, optionally filtered by capability.
| Name | Required | Description | Default |
|---|---|---|---|
| capability | No | Filter by capability: - "vision": Models that can analyze images - "image_gen": Models that can generate images - "embedding": Models that can generate embeddings - "tools": Models that support tool/function calling - "long_context": Models with 100k+ context window |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It correctly implies a read-only operation but does not explicitly state that it is non-destructive or idempotent. For a simple list tool, this is minimally adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, front-loaded sentence with no wasted words. Every part is essential.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity (1 optional param, output schema present), the description and schema together fully define the tool's behavior. No additional context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3. The description mentions 'filtered by capability' but defers to the schema for details. It adds marginal value beyond the schema's own description of the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list), resource (available OpenRouter models), and the optional filter by capability. It distinguishes well from siblings like chat and embed which are usage tools, not discovery tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide when to use list_models versus alternatives like find_models. No explicit context for usage or exclusions, leaving the agent to infer based on tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0chatembedfind_modelsgenerate_imagelist_modelsEach tool targets a distinct operation: chat for text generation, embed for embeddings, generate_image for images, find_models and list_models for model discovery with different query types. No overlap.
All tool names use lowercase with underscores, following a consistent verb or verb_noun pattern (chat, embed, generate_image, find_models, list_models).
5 tools cover the core functionalities of the OpenRouter API—chat, embedding, image generation, model search, and listing—without being excessive or insufficient.
The set covers the primary OpenRouter capabilities (chat, embed, image gen, model discovery). A minor gap is the lack of an explicit streaming tool, but chat can be parameterized for streaming.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
The OpenRouter MCP server plugs OpenRouter into the AI tools you already use. Once connected, your assistant can pull live OpenRouter data (models, prices, your credits, rankings, and docs) and send quick test messages, all without leaving your editor.
MCP server for AI dialogue using various LLM models via AceDataCloud
Focused MCP server for OpenAI image/audio generation (v2.0.0). Wraps endpoints via HAPI CLI.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/tsilva/mcp-openrouter'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
