workers-mcp

从 Claude Desktop 与 Cloudflare Worker 对话！

[!WARNING]
您应该先从这里开始——构建一个远程 MCP 服务器

您可以使用 mcp-remote，从 Claude Desktop、Cursor 和其他客户端连接到远程 MCP 服务器参见测试远程 MCP 服务器的指南。

什么是 workers-mcp？

该包提供了 CLI 工具和 Worker 内逻辑，用于将 Claude Desktop（或任何 MCP 客户端）连接到您账户上的 Cloudflare Worker，以便您可以根据自身需求进行自定义。它通过一个构建步骤实现，可以将 Worker 的 TypeScript 方法转换成如下形式：

export class ExampleWorkerMCP extends WorkerEntrypoint<Env> {
  /**
   * 生成一个随机数。这个随机数特别“随机”，因为它必须先传输到您最近的 Cloudflare PoP 进行计算，然后……嗯，好像跟熔岩灯有关？
   *
   * @return {string} 包含超级随机数字的消息
   * */
  async getRandomNumber() {
    return `您的随机数是 ${Math.random()}`
  }
  
  // ...等
}

……最终转化为 MCP 工具，供本地 Node.js 服务器暴露给 MCP 客户端使用。Node.js 服务器充当代理，在本地处理标准输入输出传输，并调用在 Cloudflare 上运行的 Worker 中的相关方法。这样一来，您就可以将应用中的任意函数或 API，或者 Cloudflare 开发者平台 中的任何服务，暴露给编码助手中的 LLM、Claude Desktop 或其他 MCP 客户端。

_{是的，我知道 Math.random() 在 Worker 上和在您的本地机器上表现是一样的，但别告诉 Claude} 🤫

使用方法

第一步：生成一个新的 Worker

使用 create-cloudflare 生成一个新的 Worker。

npx create-cloudflare@latest my-new-worker

建议选择一个“Hello World”类型的 Worker。

第二步：安装 workers-mcp

cd my-new-worker # 我总是忘记这一步
npm install workers-mcp

第三步：运行 setup 命令

npx workers-mcp setup

注意：如果出现问题，请运行 npx workers-mcp help。

第四步..♾️：迭代开发

更改 Worker 代码后，只需运行 npm run deploy 即可同时更新 Claude 关于您函数的元数据以及您正在运行的 Worker 实例。

然而，如果您更改了方法名称、参数，或者增删了方法，Claude 将不会看到这些更新，直到您重新启动它。

您通常不需要再次运行 npx workers-mcp install:claude，但如果想排除 Claude 配置作为错误来源，也可以安全地执行此操作。

与其他 MCP 客户端配合使用

Cursor

要让您的 Cloudflare MCP 服务器在 Cursor 中正常工作，您需要将配置文件中的“command”和“args”合并为一个字符串，并将其类型设置为“command”。

例如，如果您的配置文件如下：

{
  "mcpServers": {
    "your-mcp-server-name": {
      "command": "/path/to/workers-mcp",
      "args": [
        "run",
        "your-mcp-server-name",
        "https://your-server-url.workers.dev",
        "/path/to/your/project"
      ],
      "env": {}
    }
  }
}

那么在 Cursor 中，创建一个 MCP 服务器条目时：

• 类型设置为 command
• 命令设置为 /path/to/workers-mcp run your-mcp-server-name https://your-server-url.workers.dev /path/to/your/project

其他 MCP 客户端

对于 Windsurf 和其他 MCP 客户端，请更新您的配置文件以包含您的 Worker，这样您就可以直接从客户端使用这些工具：

{
  "mcpServers": {
    "your-mcp-server-name": {
      "command": "/path/to/workers-mcp",
      "args": [
        "run",
        "your-mcp-server-name",
        "https://your-server-url.workers.dev",
        "/path/to/your/project"
      ],
      "env": {}
    }
  }
}

请务必用您实际的服务器名称、URL 和项目路径替换占位符。

示例

请参阅 examples 目录，了解一些使用此工具的示例：

• examples/01-hello-world 是按照上述安装说明完成后的快照。
• examples/02-image-generation 使用 Workers AI 运行 Flux 图像生成模型。Claude 非常擅长提出提示词，并且能够解读生成结果，进而决定尝试哪些新的提示词来达到您期望的效果。
• 待办：浏览器渲染
• 待办：持久化对象

workers-mcp 快速上手指南

workers-mcp 是一个连接 Claude Desktop（或其他 MCP 客户端）与 Cloudflare Worker 的工具。它允许你将 Worker 中的 TypeScript 方法自动转换为 MCP 工具，让 AI 助手能够直接调用部署在 Cloudflare 边缘网络上的函数或 API。

注意：官方建议优先构建远程 MCP 服务器。本指南基于本地代理模式，适用于快速开发和测试。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统：macOS, Linux 或 Windows (需配置好 Node.js 环境)
• Node.js：建议安装 LTS 版本 (v18+)
• Cloudflare 账号：已注册并登录
• Wrangler CLI：已安装并认证 (npx wrangler login)
• MCP 客户端：已安装 Claude Desktop、Cursor 或 Windsurf 等支持 MCP 协议的编辑器/应用

安装步骤

1. 创建新的 Worker 项目

使用 create-cloudflare 初始化一个新项目。建议选择 "Hello World" 模板以便快速开始。

npx create-cloudflare@latest my-new-worker

2. 进入项目并安装依赖

进入项目目录并安装 workers-mcp 包。

cd my-new-worker
npm install workers-mcp

提示：国内开发者若遇 npm 下载缓慢，可临时切换镜像源： npm config set registry https://registry.npmmirror.com

3. 运行设置命令

执行设置向导，该命令将配置本地代理并更新 Claude Desktop 的配置文件。

npx workers-mcp setup

如果遇到问题，可运行 npx workers-mcp help 查看帮助信息。

基本使用

1. 编写支持 MCP 的 Worker 代码

在你的 Worker 入口文件中（通常是 src/index.ts），继承 WorkerEntrypoint 并定义带有 JSDoc 注释的方法。这些注释将作为 AI 理解工具功能的依据。

import { WorkerEntrypoint } from 'cloudflare:workers';

export class ExampleWorkerMCP extends WorkerEntrypoint<Env> {
  /**
   * Generates a random number. This is extra random because it had to travel all the way to
   * your nearest Cloudflare PoP to be calculated.
   *
   * @return {string} A message containing a super duper random number
   */
  async getRandomNumber() {
    return `Your random number is ${Math.random()}`;
  }
  
  // 在此处添加更多方法...
}

2. 部署并同步元数据

修改代码后，只需运行部署命令。这将同时更新线上的 Worker 实例和 Claude 本地的函数元数据。

npm run deploy

重要提示：如果你修改了方法名称、参数或增删了方法，必须重启 Claude Desktop 才能识别变更。仅重新部署代码是不够的。

3. 在 Claude Desktop 中调用

打开 Claude Desktop，在对话框中直接描述你的需求，例如：“帮我生成一个随机数”或“调用 getRandomNumber 方法”。Claude 将自动通过 workers-mcp 代理调用你部署在 Cloudflare 上的函数并返回结果。

4. 适配其他客户端 (如 Cursor)

若需在 Cursor 中使用，需在设置中将 command 和 args 合并为单行字符串：

• Type: command
• Command: /path/to/workers-mcp run your-mcp-server-name https://your-server-url.workers.dev /path/to/your/project

请将路径、服务名和 URL 替换为你实际的项目信息。