自然语言查流量报表：Cloudflare MCP 查询 GraphQL Analytics API 实战指南

Cloudflare MCP Server 是一个面向 Cloudflare 全量 API 的 MCP 服务器，让你用一句自然语言就能查询流量报表、DNS、Workers 等 2500 多个 API 端点。本文带你实战：如何用 MCP 的execute工具查询 GraphQL Analytics API，把网站流量报表交给 AI 自动完成，无需手写繁琐请求。

一、为什么用 Cloudflare MCP 查流量报表 📊

过去想查 Cloudflare 的网站流量，你得翻 API 文档、找准 GraphQL 端点、拼好请求体，还要处理data、errors等返回结构。现在有了Cloudflare MCP Server，你只需对 AI 说一句“看下我网站最近 7 天的流量”，剩下的交给它。

它的核心亮点是Code Mode：把整个 Cloudflare OpenAPI 规范（约 2500 个端点）压缩进约 1000 token的上下文，仅靠search和execute两个工具就搞定全部调用。

Token 成本对比

数据来源 README.md，一眼可见 Code Mode 的效率优势。

二、3 步接入 Cloudflare MCP Server

1. 记下服务地址

MCP 服务地址是https://mcp.cloudflare.com/mcp。

2. 配置你的 AI 客户端

推荐OAuth 一键授权：把下面这段 JSON 加进支持 MCP 的 AI 客户端（如 Claude、Cursor 等）：

{ "mcpServers": { "cloudflare-api": { "type": "http", "url": "https://mcp.cloudflare.com/mcp" } } }

连接后会自动跳转 Cloudflare 授权页，勾选所需权限即可。

3.（可选）用 API Token

若用于 CI/CD 或自动化，可用 Cloudflare API Token 作为 Bearer Token。多账号场景请确保 Token 带有Account Resources : Read权限，服务器才能自动识别账号 ID。

💡 若你的客户端自身已启用 Code Mode，可加?codemode=false关闭它，改用逐个端点的直接工具。

三、核心原理：search + execute 两个工具搞定一切

Cloudflare MCP 只暴露 4 个工具：

工作流一目了然：

用户 / AI Cloudflare MCP Server │ │ ├── search(找端点) ────────────────────►│ 查 spec，返回匹配的 API 路径 │◄───────── [匹配的端点] ────────────────│ │ │ ├── execute(写 GraphQL 查询) ───────────►│ 沙箱执行，自动处理 GraphQL 响应 │◄───────── [流量报表数据] ──────────────│

search只读、无网络访问；execute在隔离沙箱里运行，出站被限制到 Cloudflare API，API Token 通过 props 注入、绝不进入用户代码。相关实现见 src/tools/execute.ts 与 src/tools/search.ts。

四、实战：用自然语言查流量报表 🚀

假设你问 AI：“帮我查 example.com 最近 7 天的流量和缓存命中。”AI 会分三步走：

第 1 步：search 定位 GraphQL Analytics 端点

AI 先在 OpenAPI 规范里搜索，找到 Cloudflare 的 GraphQL Analytics 端点（路径以/graphql结尾，例如/client/v4/graphql）。

第 2 步：写一段 GraphQL 查询

AI 生成如下查询，统计每日请求数、流量字节数和缓存字节数：

execute({ code: `async () => { const response = await cloudflare.request({ method: "POST", path: "/client/v4/graphql", body: { query: `query { viewer { zones(filter: { zoneTag: "your-zone-id" }) { httpRequests1dGroups(limit: 7, orderBy: [date_ASC]) { dimensions { date } sum { requests bytes cachedBytes } } } } }`, variables: {} } }); return response.result; }`, account_id: "your-account-id", });

把your-zone-id换成你站点的 Zone Tag；多账号场景再传account_id指定要查的账号。

第 3 步：execute 执行并拿回报表

execute会在沙箱里真正调用 Cloudflare API，把返回的报表数据交还给 AI，AI 再用人话总结给你。整个过程你无需手写任何fetch。完整示例见 README.md 的 “GraphQL Analytics API” 小节。

五、MCP 如何自动处理 GraphQL 响应

GraphQL 的返回结构和普通 REST 不一样（有data和errors）。MCP 的execute会自动识别路径以/graphql结尾的请求并做归一化：

• 成功：直接返回data.data里的数据；
• 部分成功：数据与错误一起返回，错误会带上出错位置（如viewer.zones）；
• 完全失败：抛出GraphQL error: ...，信息直接进入错误结果。

这段逻辑写在 src/tools/execute.ts，对应行为测试在 tests/executor.test.ts。这意味着你无需关心 GraphQL 返回格式，AI 拿到的永远是干净、可解读的结构。

六、流量报表还能查哪些维度？

除了基础的requests/bytes/cachedBytes，GraphQL Analytics API 还支持按国家、协议、缓存状态等**维度（dimensions）**分组，并可用httpRequests1d（单条）与httpRequests1dGroups（分组）两种数据集，自定义时间范围与排序。

若你的需求偏向Zero Trust / 网关类数据集（access-logins、gateway-http等），MCP 还生成了一组 REST 工具，例如analytics_query_summary（汇总）、analytics_query_timeseries（时序）、analytics_query_top_n（Top-N），定义见 src/generated/forge-mcp/analytics/query/tools.ts。

七、常见问题与排错

• 提示权限不足 / insufficient_scope：说明 OAuth 连接缺某个 scope，服务器会引导你重新授权、补上所需权限后自动重试。
• 列表返回空：部分端点在缺权限时返回空列表而非报错。确认账号里确有数据却查到空，多半是权限问题，补 scope 即可。
• 结果被截断：Code Mode 下每次工具结果上限约 6000 token，超长会保留首尾并标注--- TRUNCATED ---，不影响 JSON 合法性。
• 多账号不知查哪个：先用whoami或search列出账号，再在execute里传account_id指定。

八、小结

Cloudflare MCP Server 用 Code Mode 把 2500 多个 API 端点压进约 1000 token，让你用一句自然语言就能查流量报表、管 DNS、部署 Workers。查 GraphQL Analytics API 时，execute工具会自动识别端点并归一化响应——你只管提问，AI 负责找端点、写查询、拿结果。把服务地址加进你的 AI 客户端，今天就试试“帮我看看网站流量”吧。

核心模块：src/tools/execute.ts · src/tools/search.ts · src/tools/whoami.ts