About OpenRouter
OpenRouter is a Python MCP server that lets MCP hosts call OpenRouter models through local stdio tools. It covers chat, image generation, embeddings, and model discovery, with commands to install or remove it in supported clients.
Key features
- 01Send chat requests to OpenRouter models
- 02Generate images and optionally save to a local path
- 03Create embeddings from text
- 04List models by capability
- 05Search model names and slugs
Use cases
- 01Ask an OpenRouter model to summarize a file
- 02Generate an image with a selected model
- 03Create embeddings for text
- 04Find models or filter them by capability
MCP support
The server exposes chat, image generation, embeddings, and model discovery tools to MCP clients. Its installer supports Codex, Claude Code, and opencode; tool calls require OPENROUTER_API_KEY.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
uvx mcp-openrouterOPENROUTER_API_KEYSecretOpenRouter API key used to authenticate tool requests.DEFAULT_TEXT_MODELDefault model slug for chat tool calls when no model is provided.DEFAULT_IMAGE_MODELDefault model slug for image generation tool calls.DEFAULT_CODE_MODELDefault model slug for code-oriented tasks.DEFAULT_VISION_MODELDefault model slug for vision-capable tool calls.DEFAULT_EMBEDDING_MODELDefault model slug for embedding tool calls when no model is provided.Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.
Tools
5Saved tool list · updated 2w ago
| Parameter | Type | Required | Description |
|---|---|---|---|
| seed | any | No | Random seed for deterministic outputs |
| stop | any | No | List of stop sequences |
| model | any | No | Model identifier (e.g., "anthropic/claude-sonnet-4", "openai/gpt-4o"). If not specified, uses DEFAULT_TEXT_MODEL environment variable. |
| top_k | any | No | Top-k sampling (number of top tokens to consider) |
| top_p | any | No | Nucleus sampling threshold 0-1 |
| prompt | any | No | User message to send (provide either prompt or messages, not both) |
| system | any | No | Optional system prompt to set context |
| messages | any | No | Multi-turn conversation as a list of {role, content} dicts (provide either prompt or messages, not both) |
| provider | any | No | Provider routing control (e.g., {"order": ["Anthropic", "Google"]}) |
| json_mode | boolean | No | If True, request JSON-formatted response (backward compat) |
| max_tokens | any | No | Maximum tokens in response (model default if not specified) |
| temperature | any | No | Sampling temperature 0-2 (model default if not specified) |
| response_format | any | No | Response format spec, e.g. {"type": "json_schema", ...}. Supersedes json_mode if both provided. |
| presence_penalty | any | No | Penalize tokens already present (-2 to 2) |
| reasoning_effort | any | No | Reasoning effort level: "minimal", "medium", or "high" |
| assistant_prefill | any | No | Text to prefill the assistant response with |
| frequency_penalty | any | No | Penalize repeated tokens (-2 to 2) |
Details
From the project README
🚀 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
Install the published server into every detected MCP client:
uvx mcp-openrouter install --yes
Install into selected clients:
uvx mcp-openrouter install --yes --clients codex,claude,opencode
Run 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-openrouter
mcp-openrouter with no arguments starts the stdio server. The explicit command is uv run mcp-openrouter serve.
Commands
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/
Tools
| Tool | Purpose |
|---|---|
chat | Send a prompt or message list to an OpenRouter chat model. |
generate_image | Generate one image and optionally save it to an absolute local path. |
embed | Generate embeddings for a string or list of strings. |
list_models | List models, optionally filtered by vision, image_gen, embedding, tools, or long_context. |
find_models | 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"
Configuration
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-2312
The 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.
Notes
- 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_pathmust be absolute, for example/Users/you/output.png.- Unit tests mock network calls.
tests/test_tools.pyrequires a liveOPENROUTER_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 ismake release-x.y.z.
Local MCP Development
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-openrouter
Codex:
codex mcp add openrouter -- keyenv run --manifest /path/to/mcp-openrouter/.keyenv.toml -- uv run --directory /path/to/mcp-openrouter mcp-openrouter
opencode:
{
"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
}
}
}
Architecture
License
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.