mcp-openrouter 1.1.0

MCP server providing access to 300+ AI models via OpenRouter

mcp-openrouter

🚀 Access 300+ AI models through a single MCP server — text, images, embeddings, and model discovery at your fingertips 🤖

Overview

mcp-openrouter is an MCP (Model Context Protocol) server that provides seamless access to OpenRouter's extensive catalog of AI models. Use Claude, GPT, Gemini, Llama, and 300+ other models through a unified interface.

Features

• ✨ Text Completion — Chat with any OpenRouter model (Claude, GPT, Gemini, Mistral, etc.)
• 🎨 Image Generation — Create images with DALL-E, Gemini, and other image models
• 📐 Embeddings — Generate vector embeddings with Mistral, OpenAI, Gemini, and other embedding models
• 🔍 Model Discovery — List and search 300+ models by capability
• ⚡ Persistent Connection — No repeated setup or permission prompts
• 🔧 Zero Config — Just set your API key and go

Quick Start

Installation

uvx mcp-openrouter install

The installer auto-detects codex, claude, and opencode on your PATH, asks which detected clients should get the openrouter MCP server, stores your OPENROUTER_API_KEY in each selected client config, and registers the production runtime command uvx mcp-openrouter.

Requirements:

• uv installed
• an OpenRouter API key from openrouter.ai/keys

If OPENROUTER_API_KEY is already set in your shell, the installer reuses it. Otherwise it prompts securely.

Non-interactive install

Install into all detected clients:

uvx mcp-openrouter install --yes

Install only specific clients:

uvx mcp-openrouter install --yes --clients codex,claude

Replace existing openrouter configs automatically:

uvx mcp-openrouter install --yes --force

uvx mcp-openrouter install --yes --api-key sk-or-v1-...

What gets installed

• Codex: codex mcp add openrouter --env OPENROUTER_API_KEY=... -- uvx mcp-openrouter
• Claude Code: claude mcp add -s user -e OPENROUTER_API_KEY=... openrouter -- uvx mcp-openrouter
• opencode: writes openrouter under ~/.opencode/settings.json in the mcp object

If an existing openrouter config already matches, the installer skips it. If it differs, the interactive installer asks before replacing it, and --force replaces it automatically.

Uninstall

codex mcp remove openrouter
claude mcp remove -s user openrouter

For opencode, remove the openrouter entry from ~/.opencode/settings.json under mcp.

Running the server directly

uvx mcp-openrouter serve

mcp-openrouter with no arguments also starts the stdio MCP server.

Default Models

Configure default models for different use cases. When set, the model parameter becomes optional in tool calls:

# Add to your .env file
DEFAULT_TEXT_MODEL=anthropic/claude-sonnet-4
DEFAULT_IMAGE_MODEL=google/gemini-3-pro-image-preview
DEFAULT_CODE_MODEL=anthropic/claude-sonnet-4
DEFAULT_VISION_MODEL=anthropic/claude-sonnet-4
DEFAULT_EMBEDDING_MODEL=mistralai/mistral-embed-2312

These are included in .env.example — copy it to .env and adjust as needed.

Tools

Tool	Description
chat	Send chat completion requests to any model
generate_image	Generate images with image models
embed	Generate vector embeddings for text
list_models	List available models, filter by capability
find_models	Search for models by name

Examples

Chat with any model:

Use openrouter chat with anthropic/claude-sonnet-4 to explain quantum computing

Generate an image:

Use openrouter generate_image with google/gemini-3-pro-image-preview to create a logo for my app

Find models:

Use openrouter find_models to search for "claude"

Generate embeddings:

Use openrouter embed with mistralai/mistral-embed-2312 to embed "Hello world"

List image generation models:

Use openrouter list_models with capability "image_gen"

API Reference

chat

Send a chat completion request to any OpenRouter model.

Parameter	Type	Required	Description
prompt	string	Yes	User message to send
model	string	No*	Model identifier (e.g., anthropic/claude-sonnet-4)
system	string	No	System prompt for context
max_tokens	int	No	Maximum tokens in response
temperature	float	No	Sampling temperature (0-2)
json_mode	bool	No	Request JSON-formatted response

*Required unless DEFAULT_TEXT_MODEL is set.

generate_image

Generate an image using an OpenRouter image model.

Parameter	Type	Required	Description
prompt	string	Yes	Image description
output_path	string	Yes	Absolute path to save the image
model	string	No*	Image model (e.g., google/gemini-3-pro-image-preview)
aspect_ratio	string	No	1:1, 16:9, 9:16, 4:3, 3:4, 21:9
size	string	No	1K, 2K, or 4K
background	string	No	Background setting (e.g., transparent)

*Required unless DEFAULT_IMAGE_MODEL is set.

embed

Generate vector embeddings for text input.

Parameter	Type	Required	Description
input	string or list	Yes	Text string or list of strings to embed
model	string	No*	Embedding model (e.g., mistralai/mistral-embed-2312)
encoding_format	string	No	Output format: float or base64
dimensions	int	No	Custom embedding dimensions (model-dependent)

*Required unless DEFAULT_EMBEDDING_MODEL is set.

list_models

List available models, optionally filtered by capability.

Parameter	Type	Required	Description
capability	string	No	Filter: vision, image_gen, embedding, tools, long_context

find_models

Search for models by name or slug.

Parameter	Type	Required	Description
search_term	string	Yes	Text to search in model names

Development

# Clone the repository
git clone https://github.com/tsilva/mcp-openrouter.git
cd mcp-openrouter

# Install dependencies
uv sync --dev

# Run the server
OPENROUTER_API_KEY=your-key uv run mcp-openrouter

# Run tests
OPENROUTER_API_KEY=your-key uv run pytest tests/

# Lint
uv run ruff check src/
uv run ruff format src/

Manual development install

If you want your MCP client to run directly from a local checkout instead of the published PyPI package, register the repo path manually.

Claude Code:

claude mcp add openrouter --scope user -- uv run --directory /path/to/mcp-openrouter mcp-openrouter

Codex:

codex mcp add openrouter --env OPENROUTER_API_KEY=your-key -- uv run --directory /path/to/mcp-openrouter mcp-openrouter

opencode:

Add this openrouter entry under mcp in ~/.opencode/settings.json:

{
  "type": "local",
  "command": ["uv", "run", "--directory", "/path/to/mcp-openrouter", "mcp-openrouter"],
  "environment": {
    "OPENROUTER_API_KEY": "your-key"
  },
  "enabled": true
}

Applying Code Changes

When you modify the MCP server code, Claude won't automatically pick up the changes. The server runs as a long-lived process that persists across tool calls within a session.

To apply your changes:

1. Start a new Claude Code session — Close your current terminal/conversation and open a new one. The MCP server process restarts when a new session begins.

2. Or use the /mcp command — Check server status and restart options within Claude Code.

Why this works: The installation uses uv run --directory /path/to/mcp-openrouter which executes code directly from your source directory. There's no separate "install" step needed — just restart the server process to load your changes.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT