Cloudflare MCP Server接入实战：用自然语言管理DNS与Worker-代码聚汇网

Cloudflare MCP Server接入实战：用自然语言管理DNS与Worker

本多敏行·2026-09-06·阅读 23 GEO检测（免费）

MCPModel Context ProtocolCloudflare

|难度：普通|阅读约 27 分钟

去年底开始，MCP（Model Context Protocol）这阵风就从 AI 编程工具圈一路吹到了日常开发者的面前。Claude Code、Cursor 这些工具大家都在装 MCP server，但说实话，很多 MCP 都是社区开发者塞进去的小玩具，真正由官方维护、能直接管理云端基础设施的不算多。Cloudflare 推出的官方 MCP server 是我最近实测下来比较有代表性的一个：通过它，AI 助手可以直接查询和修改 DNS 记录、部署 Worker、操作 R2 对象存储和 D1 数据库，相当于把 Cloudflare 的整张管理面“接入”了对话窗口。这篇文章不聊概念以外的东西，就写我怎么从零配置、跑通、并且踩了哪些坑，想给准备在 Claude Code 或 Cursor 里接 Cloudflare MCP 的朋友一份可以直接照着做的记录。

1. 先弄清楚：MCP 到底是个什么“协议”

1.1 从“工具调用的暴政”说起

在 MCP 出现之前，想让 AI 替我操作一个外部系统，通常只有两条路：要么让 AI 只生成代码，我自己复制去跑；要么我预先写好一套 API 调用脚本，把参数暴露给 AI 去填充。第一条路的问题是“AI 只动嘴，动手的还是我”，第二条路的问题是每接一个服务就要写一套独立脚本，还要自己管鉴权、解析返回结果、处理错误。做多了你就会发现，AI 像个刚入职但不会用内部系统的实习生，什么都要你手把手帮它对接。

MCP 想解决的正是这个割裂问题。它定义了一套统一协议，让 AI 应用（Host）通过本地或远程的 MCP Server 发现并调用外部能力。Server 只需要把工具（Tool）暴露出来，AI 客户端就能拿到这些工具的名字、参数说明和返回结构，然后自主决定“该调哪个函数”。步骤从“写脚本 -> 调 API -> 解析 JSON”简化成了“AI 知道有这个工具 -> AI 按规则发起调用 -> 你得到执行结果”。

1.2 MCP 的核心概念：Client、Server、Tool、Resource

我第一次看文档时被一堆名词绕晕了，拆开看其实不复杂：

Host：承载 AI 对话的应用，比如 Claude Desktop、Claude Code、Cursor。
Client：Host 内部负责和 Server 建立连接、管理会话的组件。
Server：暴露工具和资源的独立进程或服务，比如 Cloudflare 官方这个 MCP server。
Tool：Server 提供给 AI 的函数，比如 create_worker、list_dns_records。
Resource：Server 暴露的可读数据，通常以 URI 形式表示，AI 可以像读文件一样读取，例如 Cloudflare zone 的配置信息。

理解它们之间的关系，可以用一个“USB-C 统一接口”的类比：MCP 就是那个统一接口标准，Server 是各种外设，Host 是电脑。电脑不需要知道外设内部怎么工作，只要外设符合接口标准，插上就能用。AI 也一样，不需要关心 Cloudflare API 的鉴权方式和请求格式，只要 MCP Server 把能力包装成标准工具，它就能直接调用。

另外经常有人问 MCP 和 Skills 有什么区别。我目前的体会是，Skills 更像“提示词包”，作用是教会 AI 某种工作流程或思维方式，不一定能真正触发外部操作；MCP Tool 则是真实能握住的外部系统操作把手。两者不是替代关系，而是搭配关系：用 Skill 定义步骤，用 MCP Tool 执行动作。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. Cloudflare 为什么要做自己的 MCP server

2.1 Cloudflare 生态里值得被 AI 操作的东西

Cloudflare 现在远远不止一个 CDN，它更像一个边缘计算平台。日常开发里，我们最常打交道的资源包括：

Worker：无服务器函数，部署在全球边缘节点。
DNS Record：域名解析记录，改一条记录是高频操作。
Pages Project：静态站点和全栈应用托管。
R2 Object Storage：兼容 S3 的对象存储。
D1 Database：基于 SQLite 的边缘关系型数据库。
KV Storage：轻量键值存储。

这些资源全部有对应的 HTTP API，理论上都能被脚本管理，但 API 调用有学习成本，而且很多操作是“一次性动作”，专门写脚本不划算。MCP Server 的作用就是把这些 API 能力包装成语义化工具，让 AI 在对话中直接调用。官方仓库 @cloudflare/mcp-server-cloudflare 目前能干的活基本覆盖了上列绝大多数能力，而且因为是基于 Cloudflare OpenAPI 规范自动生成的，工具列表会随着 API 更新同步扩展。

2.2 Cloudflare MCP 的官方包和功能清单

按照官方文档，@cloudflare/mcp-server-cloudflare 大致把能力分成了几组：

Account 相关：查询账号信息、审计日志。
Zone 相关：列出域名、查看和修改 DNS 记录、管理缓存设置。
Workers 相关：创建脚本、部署版本、查看部署历史。
Pages 相关：管理项目、查看部署状态。
存储相关：读写 KV namespace、列出 R2 bucket 和对象、查询 D1 数据库。

每个能力都以一个或者多个工具的形式出现，AI 拿到任务是先阅读工具说明，再决定怎么组合调用。从实际体验来看，工具命名基本是 list_zone、create_dns_record、deploy_worker 这种直白风格，模型理解起来没有什么压力。

2.3 用了之后体验上的变化

举个高频场景：以前给客户加一条 DNS 记录，我需要登录 Dashboard、找到对应域名、点击 DNS 管理、进入 Records 列表、点 Add Record、填写类型、名称、IPv4 地址、再保存。动作不复杂，但久了你一定会嫌烦。现在我在 Claude Code 里输入“给 staging.example.com 添加一条 A 记录，指向 192.0.2.10，TTL 自动”，AI 会自己完成 zone 识别、记录类型判断、参数填充、API 调用，最后把新增记录的信息回给我。前端操作链路缩短到一句话。

这个体验的意义不只是快，还在于它可以进入自动化流程。比如你有 20 条测试域名的解析记录要批量调整，MCP 可以一次性列出来，筛选出 A 记录，再逐条更新。这类重复性运维工作，以前要么写一次性脚本，要么在 UI 里手点，现在用对话就能处理。

3. 环境准备与实操：把 Cloudflare MCP 接入 Claude Code / Cursor

3.1 前置条件

在开始之前，建议你先检查一下环境：

依赖项	要求	说明
Node.js	18 或更高版本	MCP server 是 Node 包，需要可用的 npm 环境
包管理器	npm 或 pnpm	推荐 npm，官方示例用 npx 启动
Cloudflare 账号	一个可用账号	免费套餐也可以
支持 MCP 的客户端	Claude Desktop / Claude Code / Cursor	本文以 Claude Code 和 Cursor 为例

如果平时 npm 包下载速度慢，可以先配置一下 npm 镜像源，把 registry 指到国内公共镜像，避免后面 npx 启动时反复超时。这一步虽然不是必须的，但在依赖拉取环节能省不少时间。

3.2 获取 API Token：最小权限原则

MCP Server 能操作的权限范围，完全取决于你给它配置的 API Token。强烈建议不要使用 Cloudflare 账号的 Global API Key，那相当于把所有管理权限都交给 AI 对话，一旦提示词设计不当，后果不可控。

正确做法是到 Cloudflare Dashboard 的 API Tokens 页面创建一个独立 Token。我自己的习惯是：

选择 “Edit zone DNS” 模板，优先覆盖域名解析操作。
按需添加权限，例如 Workers Scripts -> Edit、Account Settings -> Read。
在 Zone Resources 里选择 “All zones” 或者限定到某个测试域名。
创建完成后，Token 只会显示一次，立即保存。

密码管理器里存一份，代码配置里用环境变量引用，不要把 Token 硬编码进文件。

3.3 三种接入方式

方式 A：先用 npx 快速验证

在终端直接执行：

bash复制npx -y @cloudflare/mcp-server-cloudflare

如果本地已经通过 wrangler login 登录过账号，它可能会读取本地的 OAuth 配置；如果没有登录态，则需要配合环境变量使用。这个方式适合快速确认包能不能跑起来，并不适合直接作为客户端配置。

方式 B：Claude Desktop / Claude Code 配置

Claude Desktop 的配置文件路径，Windows 在 %APPDATA%\Claude\claude_desktop_config.json，macOS 在 ~/Library/Application Support/Claude/claude_desktop_config.json。把下面内容写进 mcpServers：

json复制{
  "mcpServers": {
    "cloudflare": {
      "command": "npx",
      "args": ["-y", "@cloudflare/mcp-server-cloudflare"],
      "env": {
        "CLOUDFLARE_API_TOKEN": "你的token",
        "CLOUDFLARE_ACCOUNT_ID": "你的accountId"
      }
    }
  }
}

Claude Code 同样读取这份配置内容，只是配置文件路径可能随着版本变化，通常放在 ~/.claude.json 或项目下的 .mcp.json。配置完成后重启客户端，工具列表里就能看到 cloudflare 前缀的工具。

方式 C：Cursor 配置

Cursor 的 MCP 入口在 Settings 里，也可以直接编辑项目根目录下的 .cursor/mcp.json：

json复制{
  "mcpServers": {
    "cloudflare": {
      "command": "npx",
      "args": ["-y", "@cloudflare/mcp-server-cloudflare"],
      "env": {
        "CLOUDFLARE_API_TOKEN": "你的token",
        "CLOUDFLARE_ACCOUNT_ID": "你的accountId"
      }
    }
  }
}

如果希望所有项目都能用，就放在用户级别配置里。配置完成后，打开 Cursor 的 MCP 面板，把 cloudflare 这个 server 的开关打开，再新建一次对话即可。

3.4 不用 Token 也能连：wrangler 登录态

Cloudflare MCP server 支持读取 wrangler 的本地登录配置。如果你平时已经在终端执行过 wrangler login，MCP server 可能会自动使用这套登录态，省去手动维护 Token 的麻烦。这个方案适合个人开发环境，方便是方便，但有个问题：登录态过期后，你可能会遇到奇怪的鉴权报错，排查时不容易想到。自动化任务、团队共享配置，我还是建议用独立 API Token，权限清晰，吊销也方便。

4. 实操场景：用自然语言部署 Worker 和改 DNS

4.1 场景一：对话式创建并部署 Worker

我实际测试的过程是这样的：在 Claude Code 里输入指令“创建名为 hello-cloudflare 的 Worker，代码返回一段 JSON 消息，部署到我的账号”，AI 先后调用了 listWorkers、createWorker、deployWorker 等多个工具。最终输出包含 Worker 的线上 URL。

如果不想让 AI 完全自由发挥，可以把需求描述得更具体一些，减少它猜参数的空间。例如：

text复制创建名为 hello-cloudflare 的 Worker，入口文件内容如下：
export default {
  async fetch(request, env, ctx) {
    return new Response(JSON.stringify({ message: "hello from mcp" }), {
      headers: { "content-type": "application/json" }
    });
  }
};
创建完后直接部署到当前账号。

这样做的好处是，AI 只需要执行“创建 + 写入代码 + 部署”的动作，代码内容由我确认过，降低它生成不预期逻辑的风险。部署完成后，MCP server 会返回线上 URL，你可以直接打开验证。

4.2 场景二：批量修改 DNS 记录

DNS 修改是最适合用 MCP 展示价值的高频场景。我之前处理过一个需求：把某个测试域名下的所有 A 记录从旧 IP 调整到新 IP。如果手工改，需要一条条对比，工作量不小。用 MCP 就相对轻松：

text复制列出 example.com 下所有 A 记录。
检查结束后，把 @ 和 www 的 A 记录指向 203.0.113.5，其余保持不变。

AI 会先调用 listZoneRecords 拿到当前记录列表，识别记录类型和名称，筛选出需要修改的目标，再逐条调用更新工具。如果你的记录很多，可以在提示词里要求“先列出需要变更的记录和计划，等确认后再执行”，这样等于增加了一层人工确认环节，降低误操作风险。

有个细节需要注意：Cloudflare DNS 记录包含一个“CDN 加速开关”属性，有些操作工具可能不会自动保留原值，而是在更新时重置。务必在变更后抽查几条记录，确认 TTL、加速状态这些属性和预期一致。

4.3 场景三：查 D1 数据库和列出 R2 对象

如果你是 Cloudflare 边缘计算的重度用户，D1 和 R2 也是 MCP 能发挥价值的地方。比如：

text复制查看 D1 数据库 users 表的结构，并返回前 5 行数据。

MCP server 会调用相关的查询工具，先读取 schema，再执行 SELECT。这种方式非常适合做快速数据巡检，不用打开任何客户端或编写 SQL 文件。

R2 上常见的操作是列举对象和管理 bucket。MCP 工具会处理分页参数，AI 可以根据返回结果进一步筛选。比如“列出 backup bucket 里最近一周上传的文件”，它会通过 API 返回对象元数据，再做时间过滤。

5. 常见问题与排查技巧实录

5.1 npx 启动失败或工具列表为空

我遇到的第一类问题集中在启动环节。npx 每次执行都要临时拉包，网络状况不好时会直接启动失败，表现是客户端 MCP 面板一直显示 connecting。解决办法有两个：一是先执行 npm i -g @cloudflare/mcp-server-cloudflare 全局安装，然后再把客户端配置里的 command 改成全局命令路径，例如：

json复制{
  "command": "mcp-server-cloudflare",
  "args": []
}

二是提前手动在终端跑一次 npx -y @cloudflare/mcp-server-cloudflare，把依赖拉下来，之后客户端启动会快很多。如果看到和 Node 版本相关的报错，检查 Node 是不是低于 18，建议直接升级到 20 LTS。

5.2 工具返回 403 或权限不足

MCP server 配置好了，但工具调用时返回权限错误，这个基本都是 Token 权限范围没配好。比如操作 DNS 记录时报 403，检查 Token 是否包含对应 Zone 的 Zone.DNS Edit 权限；部署 Worker 失败，检查 Workers Scripts 权限是否为 Edit，以及 Token 所属的 Account 是否和配置的 CLOUDFLARE_ACCOUNT_ID 一致。

如果你既操作 A 记录又操作 Worker，建议把相关权限都加到同一个 Token 上，但控制在最小必要范围。宁可在测试时发现缺权限再补，也不要一开始就开全量权限，后面出问题更难排查。

5.3 客户端找不到工具

配置完 MCP 后，客户端工具列表里没有 cloudflare 相关工具，先别急着怀疑配置文件。Claude Desktop 添加 MCP server 后必须完全重启，不是只新建会话；Cursor 需要在 MCP 面板里点击刷新开关，确认 server 状态是 enabled。配置文件方面，注意 JSON 里不能有注释，不能带 BOM，Token 值如果包含 $ 或引号等特殊字符，要做转义。之后查看客户端日志，通常能看到 server 的实际报错内容。

5.4 误操作风险怎么控制

MCP 给 AI 的能力是“真实可控”的，这句好话的另一面是：一旦提示词被误解，可能产生意料之外的操作。我现在的防呆策略有三层：

Token 最小权限：只授权资源范围中的单个 test zone，不碰生产环境。
提示词加确认步骤：让 AI 先输出变更计划，等我说“执行”才动手。
定期轮换 Token：每两周换一次，云端 Dashboard 里可以查看 API Token 的最近使用情况。

如果你是在团队里用，建议再叠加一条：不要把 Token 提交到 Git 仓库，配置通过环境变量或者 secret 管理工具统一注入。

6. 安全与权限控制的底层思考

6.1 MCP server 的权限边界

MCP 协议本身不解决授权问题，它的权限边界完全由 Server 实现决定。Cloudflare 官方 server 用的是你传入的 Token 权限，所以它在 AI 面前的“能力面”和你给这把钥匙开的锁一样大。这也是我反复强调不要用 Global API Key 的原因：一旦 MCP server 进程被恶意提示词引导，等于 AI 拥有了账号的全部权限。独立 Token 的好处是，出了问题及时吊销重发即可，不影响其他业务。

Token 类型	风险等级	建议
Global API Key	极高	不要在任何 MCP 配置里使用
Fine-grained API Token	低	推荐使用，按需授予权限
Wrangler OAuth 登录态	中	个人开发可用，注意过期处理

6.2 在团队中使用 Cloudflare MCP 的注意点

如果你打算把 Cloudflare MCP 配置共享给团队成员，有几点建议：

每个成员用独立的 Token，不要共用一把钥匙，方便在 Dashboard 里定位谁执行了哪些操作。
操作审计依赖 Cloudflare 的 Audit Log，这是你追踪变更来源的重要依据。
不同环境尽量隔离，比如生产域名和测试域名用不同的 Token、不同的 Zone 资源范围。
提示词层面约定俗成：所有变更操作必须带“先列计划再执行”的约束，减少 AI 自主发挥的空间。

6.3 如何扩展更多自定义能力

官方 MCP server 覆盖的是 Cloudflare OpenAPI 的通用能力，如果你有高度定制化的内部流程，比如“发布新版本到某个 Worker 后自动刷新 CDN 缓存”这种组合动作，不妨考虑自己写一个轻量 MCP server 包一层业务逻辑。Cloudflare 也提供了 @cloudflare/workers-mcp 这样的工具，可以把一个 Worker 本身暴露成 MCP server，让 AI 直接调用你定义的工具方法。这个思路适合把内部发布流程、配置回滚、监控告警等操作封装给 AI，同时保持权限受控。

我在实际测试中感受到，Cloudflare MCP 最有价值的部分不是把 API 文档变成对话，而是让基础设施操作有了“可观察、可确认、可回滚”的交互方式。但它的能力边界和安全风险也同样真实，务必把权限控制放到第一位。最后分享一个我自己的小习惯：在 shell 里加一个 alias，比如 cfclaude='claude --mcp-config ~/.config/claude/cf-mcp.json'，这样每次启动带 Cloudflare MCP 的会话就不用敲一长串参数了，切换项目时也更清爽。