使用说明

OpenRouter代理工具-MCP服务器

一个MCP（模型上下文协议）服务器，将OpenRouter上运行的AI代理与本地系统功能连接起来。它通过MCP协议公开文件操作、进程管理和命令执行，使x-ai/grok-4.1-fast模型能够智能地与您的系统交互。

安全警告⚠️

此服务器提供直接系统访问。使用前请阅读。

此MCP服务器授予对以下内容的无限制访问：

您的整个文件系统
所有具有用户权限的shell命令
运行进程信息
正在运行的用户帐户的任何功能

此服务器不适合生产环境或不受信任的环境。

有关关键的安全详细信息、文件访问限制和建议的保护措施，请参阅 USAGE.md中的安全警告部分.

特性

9系统工具：

🗂️ 文件系统 （6个工具）： read_file, write_file, list_directory, create_directory, delete_file, get_file_info
⚙️ 流程管理 （2个工具）： execute_command, list_processes
🤖 人工智能集成 （1个工具）： ask_grok -使用所有工具查询OpenRouter Grok模型

框架和集成：

建立在 mcp使用 可靠MCP协议支持框架
与集成 x-ai/grok-4.1快速 OpenRouter模型
具有完全类型安全的TypeScript
带有Inspector UI的热重载开发模式

快速开始

先决条件

Node.js 18或更高版本
npm 8或更高版本
OpenRouter API密钥（可用的免费层）

1.获取OpenRouter API密钥

访问https://openrouter.ai
注册（免费）或登录
去你的 API密钥页
复制API密钥（以开头 sk-or-v1-)

2.克隆和安装

git clone https://github.com/your-org/openrouter-mcp-server.git
cd openrouter-mcp-server
npm install

3.配置环境

cp .env.example .env

编辑 .env 并添加您的API密钥：

OPENROUTER_API_KEY=sk-or-v1-your-actual-api-key-here

4.启动服务器

开发模式（热重载）：

npm run dev

生产方式：

npm run build
npm start

预期产量：

OpenRouter Agent Tools MCP Server running on port 3000
Inspector available at: http://localhost:3000/inspector

5.使用Inspector UI进行测试

打开http://localhost:3000/inspector在浏览器中：

浏览所有可用工具
交互式测试工具
查看响应和错误消息
验证您的设置是否正常工作

可用工具

文件系统工具

工具	说明	参数
`read_file`	读取文件内容	`path` （字符串）
`write_file`	写入文件	`path`, `content` （字符串）
`list_directory`	列出目录内容	`path` （字符串）
`create_directory`	创建新目录	`path` （字符串）
`delete_file`	删除文件	`path` （字符串）
`get_file_info`	获取文件元数据（大小、日期）	`path` （字符串）

工艺工具

工具	说明	参数
`execute_command`	运行shell命令	`command` （字符串）， `cwd` （可选）
`list_processes`	列出正在运行的进程	无

AI代理工具

工具	说明	参数
`ask_grok`	使用工具访问查询Grok	`query` （字符串）， `system_prompt` （可选）

使用示例

示例1：列出目录中的文件

使用检查器：

选择 list_directory 工具
输入路径： /tmp
单击执行

答复： 显示中的所有文件和目录 /tmp

示例2：使用Grok创建报告

{
  "query": "Create a file called report.txt in /tmp containing today's date and time, then list all .txt files in /tmp",
  "system_prompt": "You are a helpful assistant. Be concise and accurate."
}

Grok将：

了解您要创建一个包含日期/时间的文件
使用 execute_command 获取当前日期
使用 write_file 创建报告
使用 execute_command 或使用list_directory查找txt文件
返回结果

示例3：直接执行命令

{
  "command": "npm list --depth=0",
  "cwd": "/Users/username/projects/my-app"
}

使用claude mcp-cli进行测试

使用以下工具测试无参数工具时 claude-mcp-cli，您必须提供一个空对象：

# Correct: Provide empty object for parameterless tools
claude-mcp-cli -s openrouter-agent tool call get_agent_history -i '{}'
claude-mcp-cli -s openrouter-agent tool call list_active_tasks -i '{}'
claude-mcp-cli -s openrouter-agent tool call clear_agent_history -i '{}'

# Incorrect: Omitting -i flag will cause validation error
claude-mcp-cli -s openrouter-agent tool call get_agent_history
# Error: Invalid input: expected record, received null

为什么？ MCP规范要求空对象 {} 对于没有参数的工具。一些CLI工具发送 null 相反，这会导致验证错误。根据MCP规范，这是预期的行为。

备注：此限制仅影响CLI测试。当从克劳德代码/桌面使用时，这些工具无需任何特殊处理即可正常工作。

带参数的测试工具

# execute_task_autonomously requires task parameter
claude-mcp-cli -s openrouter-agent tool call execute_task_autonomously -i '{"task": "Calculate 2 + 2"}'

# get_task_status requires taskId parameter
claude-mcp-cli -s openrouter-agent tool call get_task_status -i '{"taskId": "some-task-id"}'

已知限制

这 execute_task_autonomously 该工具需要Claude Code的采样功能，无法通过Claude-mcp-cli进行测试。请直接从Claude Code测试此工具。

看测试报告.md 用于全面的测试结果，包括验证、错误处理和并发请求测试。

架构概述

┌────────────────────────────────────┐
│    Your Application / CLI          │
└────────────────┬───────────────────┘
                 │ (MCP Protocol)
┌────────────────▼───────────────────┐
│   OpenRouter MCP Server            │
│                                    │
│  ┌──────────────────────────────┐  │
│  │  File System Tools (6)       │  │
│  │  Process Tools (2)           │  │
│  │  OpenRouter Integration (1)  │  │
│  └──────────────────────────────┘  │
└────────────────┬───────────────────┘
                 │ (HTTPS)
         ┌───────▼────────┐
         │ OpenRouter API │
         │  Grok 4.1 Fast │
         └────────────────┘

它是如何工作的：

您向发送查询 ask_grok 工具
服务器将您的查询与工具定义一起发送到OpenRouter
Grok分析您的请求并决定使用哪些工具
Grok返回它的推理和它将调用的工具（或可以执行它们）
你会得到结果的

发展

运行测试

npm test              # Run all tests once
npm run test:watch   # Run tests in watch mode

为生产而建

npm run build

输出到 dist/ 目录。

可用脚本

npm run dev       # Development with hot reload
npm run build     # Build for production
npm start         # Run production build
npm test          # Run tests once
npm test:watch   # Run tests in watch mode
npm run deploy    # Deploy (if configured)

文档

完整使用指南 -详细的文档、安全警告、配置、故障排除和示例
OpenRouter API文档 -OpenRouter API参考
MCP协议 -模型上下文协议规范
实施计划 -开发计划和任务分解

配置

环境变量（创建 .env 从 .env.example):

# Required
OPENROUTER_API_KEY=sk-or-v1-...        # Your OpenRouter API key

# Optional
PORT=3000                               # Server port (default: 3000)
MCP_URL=http://localhost:3000          # Base URL for MCP server
OPENROUTER_REFERER=http://localhost:3000  # Referer for OpenRouter
NODE_ENV=development                    # development or production

故障排除

端口已在使用中

PORT=3001 npm run dev

API密钥错误

确保 .env 文件存在且有效 OPENROUTER_API_KEY

权限被拒绝错误

检查文件权限，并确保服务器进程可以访问您尝试使用的路径

有关更多故障排除帮助，请参阅 USAGE.md故障排除部分

项目结构

openrouter-mcp-server/
├── index.ts                          # Main MCP server entry point
├── src/
│   ├── openrouter-client.ts          # OpenRouter API client
│   ├── tools/
│   │   ├── filesystem.ts             # File system tool implementations
│   │   ├── filesystem.test.ts        # File system tests
│   │   ├── process.ts                # Process tool implementations
│   │   └── process.test.ts           # Process tests
│   └── openrouter-client.test.ts     # Client tests
├── docs/
│   ├── USAGE.md                      # Complete usage documentation
│   └── plans/
│       └── 2025-12-08-openrouter-agent-tools.md  # Implementation plan
├── .env.example                      # Environment template
├── package.json                      # Dependencies
├── tsconfig.json                     # TypeScript config
└── README.md                         # This file

许可证

MIT-有关详细信息，请参阅许可证文件

支持与反馈

检查用法.md 文件优先
查看故障排除部分
在GitHub上报告问题：
- 问题的清晰描述
- 重现步骤
- 错误消息（已清除API密钥）
- 操作系统和Node.js版本

快乐建筑！ 启动服务器并在以下位置打开检查器http://localhost:3000/inspector开始探索工具。