mcp-openrouter

🚀 One MCP server for OpenRouter models 🚀

GitHub · PyPI · Issues

Overview

The Punchline

mcp-openrouter is a Python MCP server that gives Codex, Claude Code, opencode, and other MCP hosts access to OpenRouter's model catalog through five practical tools: chat, image generation, embeddings, model listing, and model search.

The Pain

OpenRouter exposes hundreds of models, but every agent host needs a clean way to call them with the right API key, model defaults, request shape, and host-specific MCP configuration.

The Solution

Install mcp-openrouter with uvx, persist your OPENROUTER_API_KEY, and let the server translate MCP tool calls into OpenRouter API requests with retry handling, .env support, and optional default models.

The Result

You get one local stdio MCP server for text, images, embeddings, and model discovery across supported MCP clients, without wiring each workflow to OpenRouter manually.

Features

• Unified chat requests: send prompts or multi-turn message arrays to any OpenRouter chat model, with sampling, JSON response, reasoning, provider routing, and assistant prefill options.
• Image generation: create images through OpenRouter image-capable models, control aspect ratio and size, and optionally save generated files to an absolute local path.
• Embeddings: generate vector embeddings for a string or a list of strings, including optional encoding format and dimension controls.
• Model discovery: list OpenRouter models and filter by vision, image_gen, embedding, tools, or long_context.
• Model search: find matching model slugs by name or identifier and return a compact result set for fast selection.
• Host-aware installer: detect eligible MCP clients, prompt for targets, replace stale configs only when requested, and support non-interactive installs.
• Default model configuration: make model optional per tool by setting default model environment variables.
• Retry and error handling: retry transient OpenRouter failures and return clearer messages for authentication, credits, rate limits, and moderation errors.

Quick Start

Use It Now

Install into every detected MCP client:

uvx mcp-openrouter install --yes

Install into specific clients:

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

Pass the OpenRouter key directly for non-interactive setup:

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

Replace an existing openrouter MCP config when it differs:

uvx mcp-openrouter install --yes --force

The interactive installer reuses OPENROUTER_API_KEY from your shell when it is set. Otherwise, it prompts securely.

Run Locally

git clone https://github.com/tsilva/mcp-openrouter.git
cd mcp-openrouter
uv sync --dev
OPENROUTER_API_KEY=your-key uv run mcp-openrouter

mcp-openrouter with no arguments starts the stdio MCP server. The explicit equivalent is:

OPENROUTER_API_KEY=your-key uv run mcp-openrouter serve

Check the Project

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
OPENROUTER_API_KEY=your-key uv run pytest tests/test_tools.py
OPENROUTER_API_KEY=your-key uv run pytest tests/
uv run ruff check src/
uv run ruff format src/

Integration tests in tests/test_tools.py require a live OpenRouter API key. The unit tests mock network calls.

Installation Details

The installer targets the production runtime command:

uvx mcp-openrouter

Installed host configs are equivalent to:

Uninstall from all detected clients:

uvx mcp-openrouter uninstall --yes

Uninstall from selected clients:

uvx mcp-openrouter uninstall --yes --clients claude,opencode

Manual uninstall commands:

codex mcp remove openrouter
claude mcp remove -s user openrouter

For opencode, the uninstaller removes the openrouter entry from ~/.opencode/settings.json.

Configuration

Required:

Optional defaults:

The server loads environment variables from .env in the current working directory and from the repository root when running from a checkout.

Example .env:

OPENROUTER_API_KEY=sk-or-v1-your-key-here
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

Tool Usage

Chat

Use openrouter chat with anthropic/claude-sonnet-4 to summarize this file

chat accepts either prompt or messages, not both.

*Provide one of prompt or messages.

**Required unless DEFAULT_TEXT_MODEL is set.

Generate Image

Use openrouter generate_image with google/gemini-3-pro-image-preview to create a square app icon

*Required unless DEFAULT_IMAGE_MODEL is set.

Embed

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

*Required unless DEFAULT_EMBEDDING_MODEL is set.

List Models

Use openrouter list_models with capability "image_gen"

Find Models

Use openrouter find_models to search for "claude"

Architecture

MCP host
  -> FastMCP tools in src/mcp_openrouter/server.py
  -> get_client()
  -> OpenRouterClient in src/mcp_openrouter/client.py
  -> https://openrouter.ai/api/v1

Local MCP Development

If you want an MCP host 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:

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

After changing server code, restart the MCP host session so it launches a fresh server process.

Tech Stack

• FastMCP for MCP server and tool registration.
• OpenRouter for chat, image, embedding, and model catalog APIs.
• uv for local dependency management and uvx runtime installs.
• requests for HTTP calls with explicit retry behavior.
• python-dotenv for .env loading during local development.
• pytest and Ruff for test and lint coverage.

Troubleshooting

Publishing Notes

• Publish the Python package to PyPI as mcp-openrouter.
• Keep server.json in sync with the released package version.
• Preserve the <!-- mcp-name: io.github.tsilva/mcp-openrouter --> marker for MCP Registry ownership verification.
• Update CHANGELOG.md before release so GitHub release notes stay readable.
• Use the Makefile helper for version bumps:

make release-1.1.8

Support

Open an issue for bugs, model compatibility problems, or host installation edge cases. Contributions are welcome when they keep the server small, explicit, and easy to verify.

License

MIT