模型上下文协议 (MCP) 服务器，可与 OpenRouter.ai 丰富的模型生态系统无缝集成。通过统一、类型安全的接口访问各种 AI 模型，该接口内置缓存、速率限制和错误处理功能。
模型访问
直接访问所有 OpenRouter.ai 模型
自动模型验证和能力检查
默认模型配置支持
性能优化
智能模型信息缓存（1小时有效）
自动速率限制管理
失败请求的指数退避
统一响应格式
所有响应的ToolResult结构一致
使用isError标志清除错误标识
带有上下文的结构化错误消息
Related MCP server: OpenRouter MCP Multimodal Server
pnpm install @mcpservers/openrouterai从OpenRouter Keys获取您的 OpenRouter API 密钥
选择默认模型（可选）
OPENROUTER_API_KEY=your-api-key-here
OPENROUTER_DEFAULT_MODEL=optional-default-model添加到您的 MCP 设置配置文件（ cline_mcp_settings.json或claude_desktop_config.json ）：
{
"mcpServers": {
"openrouterai": {
"command": "npx",
"args": ["@mcpservers/openrouterai"],
"env": {
"OPENROUTER_API_KEY": "your-api-key-here",
"OPENROUTER_DEFAULT_MODEL": "optional-default-model"
}
}
}
}所有工具都以标准化结构返回响应：
interface ToolResult {
isError: boolean;
content: Array<{
type: "text";
text: string; // JSON string or error message
}>;
}成功案例：
{
"isError": false,
"content": [{
"type": "text",
"text": "{\"id\": \"gen-123\", ...}"
}]
}错误示例：
{
"isError": true,
"content": [{
"type": "text",
"text": "Error: Model validation failed - 'invalid-model' not found"
}]
}向 OpenRouter.ai 模型发送消息：
interface ChatCompletionRequest {
model?: string;
messages: Array<{role: "user"|"system"|"assistant", content: string}>;
temperature?: number; // 0-2
}
// Response: ToolResult with chat completion data or error搜索并过滤可用型号：
interface ModelSearchRequest {
query?: string;
provider?: string;
minContextLength?: number;
capabilities?: {
functions?: boolean;
vision?: boolean;
};
}
// Response: ToolResult with model list or error获取特定型号的详细信息：
{
model: string; // Model identifier
}检查模型 ID 是否有效：
interface ModelValidationRequest {
model: string;
}
// Response:
// Success: { isError: false, valid: true }
// Error: { isError: true, error: "Model not found" }服务器提供带有上下文信息的结构化错误：
// Error response structure
{
isError: true,
content: [{
type: "text",
text: "Error: [Category] - Detailed message"
}]
}常见错误类别：
Validation Error ：输入参数无效
API Error ：OpenRouter API 通信问题
Rate Limit ：请求节流检测
Internal Error ：服务器端处理失败
处理响应：
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
}
}有关以下方面的详细信息，请参阅CONTRIBUTING.md ：
开发设置
项目结构
功能实现
错误处理指南
工具使用示例
# Install dependencies
pnpm install
# Build project
pnpm run build
# Run tests
pnpm test查看CHANGELOG.md了解最新更新，包括：
统一响应格式实现
增强的错误处理系统
类型安全接口改进
该项目根据 Apache License 2.0 获得许可 - 有关详细信息，请参阅LICENSE文件。
Sends conversational context (messages) to OpenRouter.ai for completion using a specified model. Use this for dialogue, text generation, or instruction-following tasks. Supports advanced provider routing and parameter overrides. Returns the generated text response.
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | (Optional) The specific OpenRouter model ID (e.g., "google/gemini-pro") to use for this completion request. If omitted, the server's configured default model will be used. | |
| messages | Yes | (Required) An ordered array of message objects representing the conversation history. Each object must include `role` ("system", "user", or "assistant") and `content` (the text of the message). Minimum 1 message, maximum 100. | |
| provider | No | (Optional) An object allowing fine-grained control over how OpenRouter selects the underlying AI provider for this request, overriding any server-level defaults. | |
| max_tokens | No | (Optional) Sets an upper limit on the number of tokens generated in the response. Overrides the server default if specified. Influences provider routing based on model context limits. | |
| temperature | No | (Optional) Controls the randomness of the generated output. Ranges from 0.0 (deterministic) to 2.0 (highly random). Affects creativity versus coherence. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions 'advanced provider routing and parameter overrides' and that it returns a 'generated text response', but does not disclose important behaviors such as authentication requirements, rate limits, what happens on failure, or whether the request is destructive. The description is adequate but not comprehensive for an unannotated tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loaded with the primary action, and contains no filler. Every sentence adds meaningful information: action, use cases, and key features.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description mentions returning 'the generated text response' but does not specify the exact output structure (e.g., whether it's a raw string or an object with choices). With no output schema, more detail would be helpful. It covers the main purpose and parameters adequately but lacks detail on error handling or response format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds context like 'advanced provider routing and parameter overrides' which connects to the provider parameter, but does not elaborate on the semantics of individual parameters beyond what the schema already provides. The description adds marginal value over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that it sends conversational messages to OpenRouter.ai for completion using a specified model, explicitly listing use cases like dialogue, text generation, and instruction-following. This effectively distinguishes it from sibling tools (get_model_info, search_models, validate_model) which are about model metadata, not generating completions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description tells when to use the tool ('for dialogue, text generation, or instruction-following tasks') but does not explicitly state when not to use it or provide alternatives. Given the sibling tools are unrelated, the guidance is clear enough but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves the complete metadata for a single OpenRouter.ai model specified by its unique ID. Use this when you know the model ID and need its full details (pricing, context limits, capabilities, etc.). Returns a model information object.
| Name | Required | Description | Default |
|---|---|---|---|
| model | Yes | (Required) The unique identifier string of the OpenRouter.ai model whose details are being requested. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description adequately discloses the read-only nature and the type of information returned (pricing, limits, capabilities). However, it does not discuss rate limits or authentication requirements, which are acceptable for a simple retrieval tool without annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first states the action and resource, second provides usage guidance and output description. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read tool with no output schema, the description covers what the tool does, when to use it, and what it returns. It is complete enough for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description's mention of 'unique ID' mirrors the schema description. No additional semantics are added beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves complete metadata for a single model by ID, distinguishing it from siblings like search_models (which likely doesn't require exact ID) and chat_completion (generates completions).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises using the tool when the model ID is known and full details are needed, but does not mention when not to use or name alternatives directly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Queries the OpenRouter.ai model registry, filtering by various criteria like capabilities, pricing, or provider. Use this to discover models suitable for specific needs. Returns a list of matching model metadata objects.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | (Optional) Limits the number of matching models returned in the response. Must be between 1 and 50. Defaults to 10. | |
| query | No | (Optional) A text query string to search within model names, descriptions, and provider details. | |
| provider | No | (Optional) Restricts the search to models offered by a specific provider ID (e.g., "openai", "anthropic"). | |
| capabilities | No | (Optional) An object specifying required model capabilities. | |
| maxPromptPrice | No | (Optional) Filters for models whose price for processing 1,000 prompt tokens is less than or equal to this value. | |
| maxContextLength | No | (Optional) Filters for models that support at most the specified context window size (in tokens). | |
| minContextLength | No | (Optional) Filters for models that support at least the specified context window size (in tokens). | |
| maxCompletionPrice | No | (Optional) Filters for models whose price for generating 1,000 completion tokens is less than or equal to this value. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. It describes a query operation returning metadata, which implies non-destructive behavior, but it doesn't specify authentication, rate limits, or potential side effects. Adequate but minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the main action and filtering intent. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description at least states the return type (list of metadata objects). All 8 parameters have schema descriptions, and the description covers the core use case. Lacks mention of pagination or ordering, but the limit parameter mitigates this slightly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions. The description adds high-level purpose ('filtering by various criteria') but does not introduce meaning beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it queries the model registry with filtering, and differentiates from siblings like chat_completion (generation) and get_model_info (single model details). The phrase 'Use this to discover models' directly indicates purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this to discover models suitable for specific needs.' While it doesn't list when not to use or alternatives, the sibling context provides differentiation, making usage guidance clear if not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verifies if a given model ID exists within the OpenRouter.ai registry. Use this for a quick check of model ID validity before making other API calls. Returns a boolean value (true if valid, false otherwise).
| Name | Required | Description | Default |
|---|---|---|---|
| model | Yes | (Required) The unique identifier string of the OpenRouter.ai model to check for validity. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses that the tool returns a boolean ('true if valid, false otherwise') and the action is a read-only existence check. No contradictions or hidden behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no extraneous information. The key information (verb, resource, when to use, return value) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, boolean return), the description is nearly complete. It lacks details on error states or network requirements, but these are minor for a simple existence check.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter 'model'. The description adds little beyond the schema—it restates the purpose but doesn't provide additional format or usage details. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the verb 'Verifies' and resource 'model ID exists within OpenRouter registry', clearly distinguishing from sibling tools like get_model_info (which likely returns details) and search_models (which is for searching).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: 'Use this for a quick check of model ID validity before making other API calls.' This tells when to use it, though it doesn't explicitly state alternatives or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.1chat_completionget_model_infosearch_modelsvalidate_modelScored across 4 tools
All four tools serve clearly distinct purposes: chat_completion generates text, get_model_info retrieves details for a specific model, search_models filters models by criteria, and validate_model checks model existence. No overlap or ambiguity.
All tool names follow a consistent verb_noun pattern (chat_completion, get_model_info, search_models, validate_model) using snake_case. This makes the API predictable and easy to use.
With 4 tools, the set is well-scoped for OpenRouter's purpose: one core action (chat), two for model discovery (get and search), and one for validation. No bloat or deficiency.
The tool set covers the essential workflows: chatting, retrieving model metadata, searching for models, and verifying model existence. No critical missing functionality for typical use.
OpenRouter for tools and data. Compare catalog providers and call them from one hosted MCP endpoint.
AI model routing on your own vendor keys: pick the best model per prompt, or route and run it.
The OpenRouter MCP server plugs OpenRouter into the AI tools you already use. Once connected, your assistant can pull live OpenRouter data (models, prices, your credits, rankings, and docs) and send quick test messages, all without leaving your editor.
