内容
# OpenRouter MCP 服务器
[](https://github.com/heltonteixeira/openrouterai)
[](CHANGELOG.md)
[](https://www.typescriptlang.org/)
[](LICENSE)
OpenRouter.ai 模型上下文协议（MCP）服务器，提供与 OpenRouter.ai 多样化模型生态系统的无缝集成。通过统一的、类型安全的接口访问各种 AI 模型，并内置缓存、速率限制和错误处理。
<a href="https://glama.ai/mcp/servers/xdnmf8yei0"><img width="380" height="200" src="https://glama.ai/mcp/servers/xdnmf8yei0/badge" alt="OpenRouter 服务器 MCP 服务器" /></a>
## 功能特点
- **模型访问**
- 直接访问所有 OpenRouter.ai 模型
- 自动模型验证和能力检查
- 默认模型配置支持
- **性能优化**
- 智能模型信息缓存（1 小时过期）
- 自动速率限制管理
- 失败请求的指数退避
- **统一响应格式**
- 所有响应的 `ToolResult` 结构一致
- 使用 `isError` 标志进行清晰的错误识别
- 带有上下文的结构化错误消息
## 安装
```bash
pnpm install @mcpservers/openrouterai
```
## 配置
### 前置条件
1. 从 [OpenRouter Keys](https://openrouter.ai/keys) 获取您的 OpenRouter API 密钥
2. 选择默认模型（可选）
### 环境变量
* `OPENROUTER_API_KEY`：**必填**。您的 OpenRouter API 密钥。
* `OPENROUTER_DEFAULT_MODEL`：可选。请求中未指定时的默认模型（例如，`openrouter/auto`）。
* `OPENROUTER_MAX_TOKENS`：可选。如果请求中未提供 `max_tokens`，则默认生成最大令牌数。
* `OPENROUTER_PROVIDER_QUANTIZATIONS`：可选。默认量化级别的逗号分隔列表（例如，`fp16,int8`），如果请求中未提供 `provider.quantizations`，则使用。 （第一阶段）
* `OPENROUTER_PROVIDER_IGNORE`：可选。默认忽略的提供商名称的逗号分隔列表（例如，`mistralai,openai`），如果请求中未提供 `provider.ignore`，则使用。 （第一阶段）
* `OPENROUTER_PROVIDER_SORT`：可选。提供商的默认排序顺序（"price"、"throughput" 或 "latency"）。由 `provider.sort` 参数覆盖。 （第二阶段）
* `OPENROUTER_PROVIDER_ORDER`：可选。默认优先的提供商 ID 列表（JSON 数组字符串，例如，`'["openai/gpt-4o", "anthropic/claude-3-opus"]'`）。由 `provider.order` 参数覆盖。 （第二阶段）
* `OPENROUTER_PROVIDER_REQUIRE_PARAMETERS`：可选。默认布尔值（`true` 或 `false`），仅使用支持所有指定请求参数的提供商。由 `provider.require_parameters` 参数覆盖。 （第二阶段）
* `OPENROUTER_PROVIDER_DATA_COLLECTION`：可选。默认数据收集策略（"allow" 或 "deny"）。由 `provider.data_collection` 参数覆盖。 （第二阶段）
* `OPENROUTER_PROVIDER_ALLOW_FALLBACKS`：可选。默认布尔值（`true` 或 `false`），控制首选提供商失败时的备用行为。由 `provider.allow_fallbacks` 参数覆盖。 （第二阶段）
```env
# 示例 .env 文件内容
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
```
### 设置
将以下内容添加到您的 MCP 设置配置文件（`cline_mcp_settings.json` 或 `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"
}
}
}
}
```
## 响应格式
所有工具返回标准化的结构响应：
```typescript
interface ToolResult {
isError: boolean;
content: Array<{
type: "text";
text: string; // JSON 字符串或错误消息
}>;
}
```
**成功示例：**
```json
{
"isError": false,
"content": [{
"type": "text",
"text": "{\"id\": \"gen-123\", ...}"
}]
}
```
**错误示例：**
```json
{
"isError": true,
"content": [{
"type": "text",
"text": "Error: 模型验证失败 - 'invalid-model' 未找到"
}]
}
```
## 可用工具
### `chat_completion`
向 OpenRouter Chat Completions API 发送请求。
**输入模式：**
* `model`（字符串，可选）：要使用的模型（例如，`openai/gpt-4o`，`google/gemini-pro`）。覆盖 `OPENROUTER_DEFAULT_MODEL`。如果两者均未设置，则默认为 `openrouter/auto`。
* **模型后缀：** 你可以为模型 ID 附加 `:nitro`（例如，`openai/gpt-4o:nitro`），以便在可用时路由到更快、更具实验性的版本。附加 `:floor`（例如，`mistralai/mistral-7b-instruct:floor`），使用模型的最低成本变体，通常适用于测试或低成本任务。注意：`：nitro` 和 `:floor` 变体的可用性取决于 OpenRouter。
* `messages`（数组，必填）：符合 OpenAI 聊天完成格式的消息对象数组。
* `temperature`（数字，可选）：采样温度。默认为 1。
* `max_tokens`（数字，可选）：完成时要生成的最大令牌数。覆盖 `OPENROUTER_MAX_TOKENS`。
* `provider`（对象，可选）：提供商路由配置。覆盖相应的 `OPENROUTER_PROVIDER_*` 环境变量。
* `quantizations`（字符串数组，可选）：要过滤的量化级别列表（例如，`["fp16", "int8"]`）。仅考虑与这些级别之一匹配的模型。覆盖 `OPENROUTER_PROVIDER_QUANTIZATIONS`。 （第一阶段）
* `ignore`（字符串数组，可选）：要排除的提供商名称列表（例如，`["openai", "anthropic"]`）。来自这些提供商的模型将不被使用。覆盖 `OPENROUTER_PROVIDER_IGNORE`。 （第一阶段）
* `sort`（"price" | "throughput" | "latency"，可选）：按指定条件排序提供商。覆盖 `OPENROUTER_PROVIDER_SORT`。 （第二阶段）
* `order`（字符串数组，可选）：优先的提供商 ID 列表（例如，`["openai/gpt-4o", "anthropic/claude-3-opus"]`）。覆盖 `OPENROUTER_PROVIDER_ORDER`。 （第二阶段）
* `require_parameters`（布尔值，可选）：如果为 true，则仅使用支持所有指定请求参数的提供商（例如，工具、函数、温度）。覆盖 `OPENROUTER_PROVIDER_REQUIRE_PARAMETERS`。 （第二阶段）
* `data_collection`（"allow" | "deny"，可选）：指定提供商是否可以收集请求中的数据。覆盖 `OPENROUTER_PROVIDER_DATA_COLLECTION`。 （第二阶段）
* `allow_fallbacks`（布尔值，可选）：如果为 true（默认），则允许在首选提供商失败或不可用时退回到其他提供商。如果为 false，则如果首选提供商无法使用，则请求失败。覆盖 `OPENROUTER_PROVIDER_ALLOW_FALLBACKS`。 （第二阶段）
**示例用法：
```json
{
"tool": "chat_completion",
"arguments": {
"model": "anthropic/claude-3-haiku",
"messages": [
{ "role": "user", "content": "解释 AI 模型中的量化概念。" }
],
"max_tokens": 500,
"provider": {
"quantizations": ["fp16"],
"ignore": ["openai"],
"sort": "price",
"order": ["anthropic/claude-3-haiku", "google/gemini-pro"],
"require_parameters": true,
"allow_fallbacks": false
}
}
}
```
此示例请求 `anthropic/claude-3-haiku` 的补全，限制响应为 500 个令牌。它指定了提供商路由选项：优先使用 `fp16` 量化模型，忽略 `openai` 提供商，按 `price` 排序提供商，优先使用 `anthropic/claude-3-haiku` 然后是 `google/gemini-pro`，要求所选提供商支持所有请求参数（例如 `max_tokens`），并禁用备用方案（如果优先提供商无法满足请求，则失败）。
### 搜索模型
搜索和筛选可用模型：
```typescript
interface ModelSearchRequest {
query?: string;
provider?: string;
minContextLength?: number;
capabilities?: {
functions?: boolean;
vision?: boolean;
};
}
// 响应：带有模型列表或错误的 ToolResult
```
### 获取模型信息
获取有关特定模型的详细信息：
```typescript
{
model: string; // 模型标识符
}
```
### 验证模型
检查模型 ID 是否有效：
```typescript
interface ModelValidationRequest {
model: string;
}
// 响应：
// 成功： { isError: false, valid: true }
// 错误： { isError: true, error: "模型未找到" }
```
## 错误处理
服务器提供带有上下文信息的结构化错误：
```typescript
// 错误响应结构
{
isError: true,
content: [{
type: "text",
text: "Error: [类别] - 详细消息"
}]
}
```
**常见错误类别：**
- `Validation Error`：无效的输入参数
- `API Error`：OpenRouter API 通信问题
- `Rate Limit`：请求限制检测
- `Internal Error`：服务器端处理失败
**处理响应：**
```typescript
async function handleResponse(result: ToolResult) {
if (result.isError) {
const errorMessage = result.content[0].text;
if (errorMessage.startsWith('Error: Rate Limit')) {
// 处理速率限制
}
// 其他错误处理
} else {
const data = JSON.parse(result.content[0].text);
// 处理成功响应
}
}
```
## 开发
参见 [CONTRIBUTING.md](CONTRIBUTING.md) 了解详细内容：
- 开发设置
- 项目结构
- 功能实现
- 错误处理指南
- 工具使用示例
```bash
# 安装依赖
pnpm install
# 构建项目
pnpm run build
# 运行测试
pnpm test
```
## 更新日志
参见 [CHANGELOG.md](./CHANGELOG.md) 了解最近的更新，包括：
- 统一响应格式实现
- 增强的错误处理系统
- 类型安全接口改进
## 许可证
该项目根据 Apache License 2.0 许可 - 参见 [LICENSE](LICENSE) 文件了解详情。
连接信息
猜你喜欢
暂无推荐服务器