remote-mcp-server

使用 Cloudflare 提供网页搜索功能的远程 MCP 服务

一个已部署到 Cloudflare Workers 的生产就绪型远程 MCP（Model Context Protocol）服务，实现了问候工具和网页搜索功能。此服务展示了如何构建和部署 Cursor 和 Claude Desktop 等 AI 助手可使用的自定义工具。

概述

本项目是以下功能的参考实现：

• 构建自定义 MCP 服务
• 实现 OAuth 身份验证
• 将 MCP 服务部署到 Cloudflare Workers
• 将 AI 助手连接到自定义工具
• 集成网页搜索功能

功能

• 🚀 部署在 Cloudflare Workers 上的远程 MCP 服务
• 🔐 用于安全访问的 OAuth 身份验证
• 👋 用于测试 MCP 功能的简单问候工具
• 🔍 用于实时信息检索的网页搜索工具
• 🤖 兼容 Cursor 和 Claude Desktop
• 📊 内置 MCP Inspector 支持
• 📦 简单的本地开发设置
• 🛠️ 生产就绪的部署配置

前置条件

• Node.js 18 或更高版本
• pnpm 包管理器
• Cloudflare 账户（用于部署）
• Git
• 网页搜索服务的 API 密钥（可选）

本地开发

1. 克隆代码库：

# Using HTTPS
git clone https://github.com/cloudflare/ai.git

# Or using SSH
git clone [email protected]:cloudflare/ai.git

2. 安装依赖项：

cd ai
pnpm install

3. 配置环境变量（可选）：

# Create a .env file
cp .env.example .env

# Add your web search API key if needed
WEB_SEARCH_API_KEY=your_api_key_here

4. 启动开发服务：

npx nx dev remote-mcp-server

服务将在 http://localhost:8787/ 上运行

集成指南

连接到 Cursor

1. 打开 Cursor，前往 Settings > AI Settings
2. 在 MCP Configuration 部分添加：

{
  "mcpServers": {
    "greeting": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8787/sse"
      ]
    },
    "webSearch": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8787/sse"
      ]
    }
  }
}

3. 重启 Cursor
4. 出现提示时，使用任意邮箱和密码登录（用于测试的模拟身份验证）
5. 通过以下方式测试工具：
   • 让 Cursor 向某人问好
   • 请求搜索某个查询的网页结果

连接到 Claude Desktop

1. 打开 Claude Desktop，前往 Settings > Developer > Edit Config
2. 添加以下配置：

{
  "mcpServers": {
    "greeting": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8787/sse"
      ]
    },
    "webSearch": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8787/sse"
      ]
    }
  }
}

3. 重启 Claude Desktop
4. 使用任意邮箱和密码登录
5. 通过以下方式测试工具：
   • 让 Claude 向某人问好
   • 请求搜索某个查询的网页结果

使用 MCP Inspector 测试

1. 启动 Inspector：

npx @modelcontextprotocol/inspector

2. 在浏览器中打开 http://localhost:5173
3. 配置连接：
   • 将 Transport Type 设为 SSE
   • 输入 http://localhost:8787/sse 作为 MCP 服务 URL
   • 点击“Connect”
4. 使用任意邮箱和密码登录
5. 测试两个工具：
   • 使用问候工具发送问候
   • 使用网页搜索工具搜索信息

可用工具

问候工具

• 用于生成个性化问候的简单工具
• 用法：让 AI 按姓名向某人问好
• 示例：“请向 John 问好”

网页搜索工具

• 执行实时网页搜索
• 返回相关搜索结果
• 用法：让 AI 搜索信息
• 示例：“搜索有关 AI 的最新新闻”

部署

部署到 Cloudflare

1. 创建 KV 命名空间：

npx wrangler kv namespace create OAUTH_KV

2. 将 KV 命名空间 ID 添加到 wrangler.jsonc
3. 在 Cloudflare 中配置环境变量：
   • 前往 Workers > Your Worker > Settings > Variables
   • 如有需要，添加网页搜索 API 密钥
4. 部署到 Cloudflare：

npm run deploy

连接到已部署的服务

更新 Cursor 或 Claude Desktop 中的配置，使用你的 Worker URL：

{
  "mcpServers": {
    "greeting": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-worker-name.your-account.workers.dev/sse"
      ]
    },
    "webSearch": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-worker-name.your-account.workers.dev/sse"
      ]
    }
  }
}

故障排除

常见问题

1. 连接问题

   • 确认服务正在本地运行
   • 检查端口 8787 是否可用
   • 确保防火墙未阻止连接

2. 身份验证问题

   • 清除身份验证文件：

   rm -rf ~/.mcp-auth
   

   • 重启应用程序
   • 尝试重新登录

3. 工具无法正常工作

   • 确认配置正确
   • 检查浏览器控制台中的错误
   • 查看服务日志，排查问题

4. 网页搜索问题

   • 确认 API 密钥配置正确
   • 检查是否已达到 API 速率限制
   • 确保搜索查询格式正确

调试

1. 直接测试连接：

npx mcp-remote http://localhost:8787/sse

2. 检查服务日志：

npx wrangler tail

3. 监控网页搜索请求：

npx wrangler tail --format=pretty

贡献

欢迎贡献！请随时提交 Pull Request。

许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

支持

如果遇到任何问题或有疑问：

• 在 GitHub 上提交 issue
• 查看 Cloudflare Workers 文档
• 查看 MCP 规范
• 查阅 Web Search API 文档