OpenRouter.aiの多様なモデルエコシステムとのシームレスな統合を実現するモデルコンテキストプロトコル（MCP）サーバー。キャッシュ、レート制限、エラー処理を内蔵した統合型セーフインターフェースを通じて、様々なAIモデルにアクセスできます。
モデルアクセス
すべてのOpenRouter.aiモデルへの直接アクセス
自動モデル検証と機能チェック
デフォルトのモデル構成のサポート
パフォーマンスの最適化
スマートモデル情報のキャッシュ（1時間で有効期限切れ）
自動レート制限管理
失敗したリクエストに対する指数バックオフ
統一応答形式
すべてのレスポンスに一貫したToolResult構造
isErrorフラグでエラー識別をクリアする
コンテキスト付きの構造化されたエラーメッセージ
Related MCP server: OpenRouter MCP Multimodal Server
pnpm install @mcpservers/openrouteraiOpenRouter KeysからOpenRouter APIキーを取得します。
デフォルトモデルを選択する（オプション）
OPENROUTER_API_KEY=your-api-key-here
OPENROUTER_DEFAULT_MODEL=optional-default-modelMCP 設定構成ファイル ( 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.
