What can you do with this server?

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

Which integrations are available for this server?

Provides a type-safe interface for accessing and interacting with OpenRouter.ai's diverse model ecosystem

OpenRouter MCP Server

MCP Server Version TypeScript License

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

Related MCP server: MindBridge MCP Server

Installation

pnpm install @mcpservers/openrouterai

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 if max_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) if provider.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) if provider.ignore is not provided in the request. (Phase 1)
OPENROUTER_PROVIDER_SORT: Optional. Default sort order for providers ("price", "throughput", or "latency"). Overridden by provider.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 by provider.order argument. (Phase 2)
OPENROUTER_PROVIDER_REQUIRE_PARAMETERS: Optional. Default boolean (true or false) to only use providers supporting all specified request parameters. Overridden by provider.require_parameters argument. (Phase 2)
OPENROUTER_PROVIDER_DATA_COLLECTION: Optional. Default data collection policy ("allow" or "deny"). Overridden by provider.data_collection argument. (Phase 2)
OPENROUTER_PROVIDER_ALLOW_FALLBACKS: Optional. Default boolean (true or false) to control fallback behavior if preferred providers fail. Overridden by provider.allow_fallbacks argument. (Phase 2)

# Example .env file content OPENROUTER_API_KEY=your-api-key-here OPENROUTER_DEFAULT_MODEL=openrouter/auto OPENROUTER_MAX_TOKENS=1024 OPENROUTER_PROVIDER_QUANTIZATIONS=fp16,int8 OPENROUTER_PROVIDER_IGNORE=openai,anthropic OPENROUTER_PROVIDER_SORT=price OPENROUTER_PROVIDER_ORDER='["openai/gpt-4o", "anthropic/claude-3-opus"]' OPENROUTER_PROVIDER_REQUIRE_PARAMETERS=true OPENROUTER_PROVIDER_DATA_COLLECTION=deny OPENROUTER_PROVIDER_ALLOW_FALLBACKS=false

OPENROUTER_PROVIDER_QUANTIZATIONS=fp16,int8 OPENROUTER_PROVIDER_IGNORE=openai,anthropic

### Setup Add to your MCP settings configuration file (`cline_mcp_settings.json` or `claude_desktop_config.json`): ```json { "mcpServers": { "openrouterai": { "command": "npx", "args": ["@mcpservers/openrouterai"], "env": { "OPENROUTER_API_KEY": "your-api-key-here", "OPENROUTER_DEFAULT_MODEL": "optional-default-model", "OPENROUTER_MAX_TOKENS": "1024", "OPENROUTER_PROVIDER_QUANTIZATIONS": "fp16,int8", "OPENROUTER_PROVIDER_IGNORE": "openai,anthropic" } } } } ## Response Format All tools return responses in a standardized structure: ```typescript interface ToolResult { isError: boolean; content: Array<{ type: "text"; text: string; // JSON string or error message }>; }

Success Example:

{ "isError": false, "content": [{ "type": "text", "text": "{\"id\": \"gen-123\", ...}" }] }

Error Example:

{ "isError": true, "content": [{ "type": "text", "text": "Error: Model validation failed - 'invalid-model' not found" }] }

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). Overrides OPENROUTER_DEFAULT_MODEL. Defaults to openrouter/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.
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. Overrides OPENROUTER_MAX_TOKENS.
provider (object, optional): Provider routing configuration. Overrides corresponding OPENROUTER_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. Overrides OPENROUTER_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. Overrides OPENROUTER_PROVIDER_IGNORE. (Phase 1)
- sort ("price" | "throughput" | "latency", optional): Sort providers by the specified criteria. Overrides OPENROUTER_PROVIDER_SORT. (Phase 2)
- order (array of strings, optional): A prioritized list of provider IDs (e.g., ["openai/gpt-4o", "anthropic/claude-3-opus"]). Overrides OPENROUTER_PROVIDER_ORDER. (Phase 2)
- require_parameters (boolean, optional): If true, only use providers that support all specified request parameters (like tools, functions, temperature). Overrides OPENROUTER_PROVIDER_REQUIRE_PARAMETERS. (Phase 2)
- data_collection ("allow" | "deny", optional): Specify whether providers are allowed to collect data from the request. Overrides OPENROUTER_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. Overrides OPENROUTER_PROVIDER_ALLOW_FALLBACKS. (Phase 2)

Example Usage:

{ "tool": "chat_completion", "arguments": { "model": "anthropic/claude-3-haiku", "messages": [ { "role": "user", "content": "Explain the concept of quantization in AI models." } ], "max_tokens": 500, "provider": { "quantizations": ["fp16"], "ignore": ["openai"], "sort": "price", "order": ["anthropic/claude-3-haiku", "google/gemini-pro"], "require_parameters": true, "allow_fallbacks": false } } }

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:

interface ModelSearchRequest { query?: string; provider?: string; minContextLength?: number; capabilities?: { functions?: boolean; vision?: boolean; }; } // Response: ToolResult with model list or error

get_model_info

Get detailed information about a specific model:

{ model: string; // Model identifier }

validate_model

Check if a model ID is valid:

interface ModelValidationRequest { model: string; } // Response: // Success: { isError: false, valid: true } // Error: { isError: true, error: "Model not found" }

Error Handling

The server provides structured errors with contextual information:

// Error response structure { isError: true, content: [{ type: "text", text: "Error: [Category] - Detailed message" }] }

Common Error Categories:

Validation Error: Invalid input parameters
API Error: OpenRouter API communication issues
Rate Limit: Request throttling detection
Internal Error: Server-side processing failures

Handling Responses:

async function handleResponse(result: ToolResult) { if (result.isError) { const errorMessage = result.content[0].text; if (errorMessage.startsWith('Error: Rate Limit')) { // Handle rate limiting } // Other error handling } else { const data = JSON.parse(result.content[0].text); // Process successful response } }

Development

See CONTRIBUTING.md for detailed information about:

Development setup
Project structure
Feature implementation
Error handling guidelines
Tool usage examples

# Install dependencies pnpm install # Build project pnpm run build # Run tests pnpm test

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.

OpenRouter MCP Server

OpenRouter MCP Server

Features

Installation

Configuration

Prerequisites

Environment Variables

Available Tools

`chat_completion`

search_models

get_model_info

validate_model

Error Handling

Development

Changelog

License

Resources

Appeared in Searches

New MCP Servers

Latest Blog Posts

MCP directory API