The OpenRouter MCP Server provides a unified interface to interact with OpenRouter.ai's AI models through the Model Context Protocol (MCP), offering:
- Model Interaction: Send messages to AI models via chat completion with customizable parameters like temperature
- Model Discovery: Search and filter models by provider, capabilities (tools, vision, functions, JSON mode), context length, and pricing
- Model Information: Retrieve detailed specifications for any model ID and validate IDs for recognition
- Performance Optimizations: Utilizes model caching, rate limit management, and exponential backoff for retries
- Structured Responses: All results follow a standardized
ToolResult
format with clear error handling - Simple Configuration: Easy setup through environment variables and MCP configuration files
Provides a type-safe interface for accessing and interacting with OpenRouter.ai's diverse model ecosystem
OpenRouter MCP Server
A Model Context Protocol (MCP) server providing seamless integration with OpenRouter.ai's diverse model ecosystem. Access various AI models through a unified, type-safe interface with built-in caching, rate limiting, and error handling.
Features
- Model Access
- Direct access to all OpenRouter.ai models
- Automatic model validation and capability checking
- Default model configuration support
- Performance Optimization
- Smart model information caching (1-hour expiry)
- Automatic rate limit management
- Exponential backoff for failed requests
- Unified Response Format
- Consistent
ToolResult
structure for all responses - Clear error identification with
isError
flag - Structured error messages with context
- Consistent
Installation
Configuration
Prerequisites
- Get your OpenRouter API key from OpenRouter Keys
- Choose a default model (optional)
Environment Variables
OPENROUTER_API_KEY
: Required. Your OpenRouter API key.OPENROUTER_DEFAULT_MODEL
: Optional. The default model to use if not specified in the request (e.g.,openrouter/auto
).OPENROUTER_MAX_TOKENS
: Optional. Default maximum number of tokens to generate ifmax_tokens
is not provided in the request.OPENROUTER_PROVIDER_QUANTIZATIONS
: Optional. Comma-separated list of default quantization levels to filter by (e.g.,fp16,int8
) ifprovider.quantizations
is not provided in the request. (Phase 1)OPENROUTER_PROVIDER_IGNORE
: Optional. Comma-separated list of default provider names to ignore (e.g.,mistralai,openai
) ifprovider.ignore
is not provided in the request. (Phase 1)OPENROUTER_PROVIDER_SORT
: Optional. Default sort order for providers ("price", "throughput", or "latency"). Overridden byprovider.sort
argument. (Phase 2)OPENROUTER_PROVIDER_ORDER
: Optional. Default prioritized list of provider IDs (JSON array string, e.g.,'["openai/gpt-4o", "anthropic/claude-3-opus"]'
). Overridden byprovider.order
argument. (Phase 2)OPENROUTER_PROVIDER_REQUIRE_PARAMETERS
: Optional. Default boolean (true
orfalse
) to only use providers supporting all specified request parameters. Overridden byprovider.require_parameters
argument. (Phase 2)OPENROUTER_PROVIDER_DATA_COLLECTION
: Optional. Default data collection policy ("allow" or "deny"). Overridden byprovider.data_collection
argument. (Phase 2)OPENROUTER_PROVIDER_ALLOW_FALLBACKS
: Optional. Default boolean (true
orfalse
) to control fallback behavior if preferred providers fail. Overridden byprovider.allow_fallbacks
argument. (Phase 2)
OPENROUTER_PROVIDER_QUANTIZATIONS=fp16,int8 OPENROUTER_PROVIDER_IGNORE=openai,anthropic
Success Example:
Error Example:
Available Tools
chat_completion
Sends a request to the OpenRouter Chat Completions API.
Input Schema:
model
(string, optional): The model to use (e.g.,openai/gpt-4o
,google/gemini-pro
). OverridesOPENROUTER_DEFAULT_MODEL
. Defaults toopenrouter/auto
if neither is set.- Model Suffixes: You can append
:nitro
to a model ID (e.g.,openai/gpt-4o:nitro
) to potentially route to faster, experimental versions if available. Append:floor
(e.g.,mistralai/mistral-7b-instruct:floor
) to use the cheapest available variant of a model, often useful for testing or low-cost tasks. Note: Availability of:nitro
and:floor
variants depends on OpenRouter.
- Model Suffixes: You can append
messages
(array, required): An array of message objects conforming to the OpenAI chat completion format.temperature
(number, optional): Sampling temperature. Defaults to 1.max_tokens
(number, optional): Maximum number of tokens to generate in the completion. OverridesOPENROUTER_MAX_TOKENS
.provider
(object, optional): Provider routing configuration. Overrides correspondingOPENROUTER_PROVIDER_*
environment variables.quantizations
(array of strings, optional): List of quantization levels to filter by (e.g.,["fp16", "int8"]
). Only models matching one of these levels will be considered. OverridesOPENROUTER_PROVIDER_QUANTIZATIONS
. (Phase 1)ignore
(array of strings, optional): List of provider names to exclude (e.g.,["openai", "anthropic"]
). Models from these providers will not be used. OverridesOPENROUTER_PROVIDER_IGNORE
. (Phase 1)sort
("price" | "throughput" | "latency", optional): Sort providers by the specified criteria. OverridesOPENROUTER_PROVIDER_SORT
. (Phase 2)order
(array of strings, optional): A prioritized list of provider IDs (e.g.,["openai/gpt-4o", "anthropic/claude-3-opus"]
). OverridesOPENROUTER_PROVIDER_ORDER
. (Phase 2)require_parameters
(boolean, optional): If true, only use providers that support all specified request parameters (like tools, functions, temperature). OverridesOPENROUTER_PROVIDER_REQUIRE_PARAMETERS
. (Phase 2)data_collection
("allow" | "deny", optional): Specify whether providers are allowed to collect data from the request. OverridesOPENROUTER_PROVIDER_DATA_COLLECTION
. (Phase 2)allow_fallbacks
(boolean, optional): If true (default), allows falling back to other providers if the preferred ones fail or are unavailable. If false, fails the request if preferred providers cannot be used. OverridesOPENROUTER_PROVIDER_ALLOW_FALLBACKS
. (Phase 2)
Example Usage:
This example requests a completion from anthropic/claude-3-haiku
, limits the response to 500 tokens. It specifies provider routing options: prefer fp16
quantized models, ignore openai
providers, sort remaining providers by price
, prioritize anthropic/claude-3-haiku
then google/gemini-pro
, require the chosen provider to support all request parameters (like max_tokens
), and disable fallbacks (fail if the prioritized providers cannot fulfill the request).
search_models
Search and filter available models:
get_model_info
Get detailed information about a specific model:
validate_model
Check if a model ID is valid:
Error Handling
The server provides structured errors with contextual information:
Common Error Categories:
Validation Error
: Invalid input parametersAPI Error
: OpenRouter API communication issuesRate Limit
: Request throttling detectionInternal Error
: Server-side processing failures
Handling Responses:
Development
See CONTRIBUTING.md for detailed information about:
- Development setup
- Project structure
- Feature implementation
- Error handling guidelines
- Tool usage examples
Changelog
See CHANGELOG.md for recent updates including:
- Unified response format implementation
- Enhanced error handling system
- Type-safe interface improvements
License
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Provides integration with OpenRouter.ai, allowing access to various AI models through a unified interface.
Related MCP Servers
- -securityFlicense-qualityEnables AI models to interact with Jira using a standardized protocol, offering full Jira REST API integration with features like optimal performance through connection pooling, error handling, and request monitoring.Last updated -2TypeScript
- AsecurityAlicenseAqualityEnables AI agents to interact with multiple LLM providers (OpenAI, Anthropic, Google, DeepSeek) through a standardized interface, making it easy to switch between models or use multiple models in the same application.Last updated -15PythonMIT License
- AsecurityAlicenseAqualityAn AI router that connects applications to multiple LLM providers (OpenAI, Anthropic, Google, DeepSeek, Ollama, etc.) with smart model orchestration capabilities, enabling dynamic switching between models for different reasoning tasks.Last updated -361917TypeScriptMIT License
- -securityFlicense-qualityA unified API server that enables interaction with multiple AI model providers like Anthropic and OpenAI through a consistent interface, supporting chat completions, tool calling, and context handling.Last updated -JavaScript