Back to Details

mcp-cloudflare

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Cloudflare MCP Skill

Cloudflare MCP Skill

Interact with Cloudflare services via MCP: Workers, KV, R2, D1, Hyperdrive, Observability, Builds, Audit, Container Sandbox.
通过MCP与Cloudflare服务交互：Workers、KV、R2、D1、Hyperdrive、可观测性、构建、审计、容器沙箱。

File-based Pipeline (Pass Paths Only)

基于文件的流水线（仅传递路径）

When integrating troubleshooting/changes into multi-step workflows, persist all evidence and artifacts to disk, passing only paths between agents/sub-agents.
Recommended directory structure (within project): 
runs/<workflow>/active/<run_id>/
  • Input: 
    01-input/goal.md
    (symptoms/objectives), 
    01-input/context.json
    (account/worker/resource/time_range, etc.)
  • Evidence: 
    02-analysis/observability.md
    , 
    02-analysis/audit.md
    , 
    02-analysis/screenshots/
  • Plan: 
    03-plans/change-plan.md
    (write operation plan; must write here and await confirmation first)
  • Output: 
    05-final/report.md
    (conclusion + evidence chain + tool call summary + next steps)
  • Logs: 
    logs/events.jsonl
    (summary of each tool call)
在将故障排查/变更集成到多步骤工作流时，需将所有证据和工件持久化到磁盘，代理/子代理之间仅传递路径。
推荐的目录结构（项目内）：
runs/<workflow>/active/<run_id>/
  • 输入：
    01-input/goal.md
    （症状/目标）、
    01-input/context.json
    （账户/Worker/资源/时间范围等）
  • 证据：
    02-analysis/observability.md
    、
    02-analysis/audit.md
    、
    02-analysis/screenshots/
  • 计划：
    03-plans/change-plan.md
    （写入操作计划；必须先在此处编写并等待确认）
  • 输出：
    05-final/report.md
    （结论 + 证据链 + 工具调用摘要 + 后续步骤）
  • 日志：
    logs/events.jsonl
    （每个工具调用的摘要）

Permission Tiers (Core Principles)

权限层级（核心原则）

TierPurposeTool ScopeRisk Control
DiagnoseRead-only/query/troubleshootObservability, Builds, Browser, AuditDefault entry point, no write operations
ChangeCreate/modify/delete resourcesWorkers Bindings (KV/R2/D1)Requires user confirmation, post-execution verification
Super AdminHighest privilegesAll + Container SandboxOnly in isolated environments/test accounts
层级用途工具范围风险控制
诊断只读/查询/故障排查可观测性、构建、浏览器、审计默认入口，无写入操作
变更创建/修改/删除资源Workers绑定（KV/R2/D1）需要用户确认，执行后验证
超级管理员最高权限所有工具 + 容器沙箱仅用于隔离环境/测试账户

Tool Reference

工具参考

Diagnose Tier (Read-only)

诊断层级（只读）

Observability
ToolPurpose
query_worker_observability
Query logs/metrics (events, CPU, error rate)
observability_keys
Discover available fields
observability_values
Explore field values
Builds
ToolPurpose
workers_builds_list_builds
List build history
workers_builds_get_build
Get build details
workers_builds_get_build_logs
Get build logs
Browser Rendering (Page Capture)
ToolPurpose
get_url_html_content
Fetch page HTML
get_url_markdown
Convert to Markdown
get_url_screenshot
Take page screenshot
Audit Logs
ToolPurpose
auditlogs_by_account_id
Pull change history by time range
可观测性
工具用途
query_worker_observability
查询日志/指标（事件、CPU、错误率）
observability_keys
发现可用字段
observability_values
探索字段值
构建
工具用途
workers_builds_list_builds
列出构建历史
workers_builds_get_build
获取构建详情
workers_builds_get_build_logs
获取构建日志
浏览器渲染（页面捕获）
工具用途
get_url_html_content
获取页面HTML
get_url_markdown
转换为Markdown
get_url_screenshot
截取页面截图
审计日志
工具用途
auditlogs_by_account_id
按时间范围拉取变更历史

Change Tier (Write Operations)

变更层级（写入操作）

Account
ToolPurpose
accounts_list
List accounts
set_active_account
Set active account
Builds (Settings)
ToolPurpose
workers_builds_set_active_worker
⚠️ Set active worker (requires confirmation)
KV
ToolPurpose
kv_namespaces_list
List namespaces
kv_namespace_get
Get details
kv_namespace_create
Create (⚠️ requires confirmation)
kv_namespace_update
Update (⚠️ requires confirmation)
kv_namespace_delete
Delete (⚠️ requires confirmation)
R2
ToolPurpose
r2_buckets_list
List buckets
r2_bucket_get
Get details
r2_bucket_create
Create (⚠️ requires confirmation)
r2_bucket_delete
Delete (⚠️ requires confirmation)
D1
ToolPurpose
d1_databases_list
List databases
d1_database_get
Get details
d1_database_query
Execute SQL
d1_database_create
Create (⚠️ requires confirmation)
d1_database_delete
Delete (⚠️ requires confirmation)
Hyperdrive
ToolPurpose
hyperdrive_configs_list
List configs
hyperdrive_config_get
Get details
hyperdrive_config_create
Create (⚠️ requires confirmation)
hyperdrive_config_edit
Edit (⚠️ requires confirmation)
hyperdrive_config_delete
Delete (⚠️ requires confirmation)
Workers
ToolPurpose
workers_list
List workers
workers_get_worker
Get worker details
workers_get_worker_code
Get source code
账户
工具用途
accounts_list
列出账户
set_active_account
设置活跃账户
构建（设置）
工具用途
workers_builds_set_active_worker
⚠️ 设置活跃Worker（需要确认）
KV
工具用途
kv_namespaces_list
列出命名空间
kv_namespace_get
获取详情
kv_namespace_create
创建（⚠️ 需要确认）
kv_namespace_update
更新（⚠️ 需要确认）
kv_namespace_delete
删除（⚠️ 需要确认）
R2
工具用途
r2_buckets_list
列出存储桶
r2_bucket_get
获取详情
r2_bucket_create
创建（⚠️ 需要确认）
r2_bucket_delete
删除（⚠️ 需要确认）
D1
工具用途
d1_databases_list
列出数据库
d1_database_get
获取详情
d1_database_query
执行SQL
d1_database_create
创建（⚠️ 需要确认）
d1_database_delete
删除（⚠️ 需要确认）
Hyperdrive
工具用途
hyperdrive_configs_list
列出配置
hyperdrive_config_get
获取详情
hyperdrive_config_create
创建（⚠️ 需要确认）
hyperdrive_config_edit
编辑（⚠️ 需要确认）
hyperdrive_config_delete
删除（⚠️ 需要确认）
Workers
工具用途
workers_list
列出Workers
workers_get_worker
获取Worker详情
workers_get_worker_code
获取源代码

Super Admin Tier (Container Sandbox)

超级管理员层级（容器沙箱）

ToolPurpose
container_initialize
Initialize container (~10 min lifecycle)
container_exec
Execute command
container_file_write
Write file
container_file_read
Read file
container_files_list
List files
container_file_delete
Delete file
Container Notes: No persistent state, short lifespan, only for temporary tasks (running tests/reproducing issues/parsing data).
工具用途
container_initialize
初始化容器（生命周期约10分钟）
container_exec
执行命令
container_file_write
写入文件
container_file_read
读取文件
container_files_list
列出文件
container_file_delete
删除文件
容器注意事项：无持久化状态，生命周期短，仅用于临时任务（运行测试/复现问题/解析数据）。

Security Rules (Must Follow)

安全规则（必须遵守）

Read Operations

读取操作

  1. Define scope first: account / worker / resource ID
  2. No account? Run 
    accounts_list
    first
  3. Conclusions must have evidence chain: logs/screenshots/audit records
  1. 先定义范围：账户 / Worker / 资源ID
  2. 无账户？先运行
    accounts_list
  3. 结论必须有证据链：日志/截图/审计记录

Write Operations (Three-step Flow)

写入操作（三步流程）

1. Plan: Read current state first (list/get)
2. Confirm: Output precise change (name/ID/impact scope), await user confirmation
3. Execute: create/delete/update
4. Verify: audit logs + observability confirm no new errors
1. 计划：先读取当前状态（list/get）
2. 确认：输出精确的变更内容（名称/ID/影响范围），等待用户确认
3. 执行：创建/删除/更新
4. 验证：通过审计日志 + 可观测性确认无新错误

Prohibited Actions

禁止操作

  • ❌ Execute create/delete/update without confirmation
  • ❌ Delete production resources (unless user explicitly says "delete production xxx")
  • ❌ Use Super Admin privileges in non-isolated environments
  • ❌ Use container sandbox as persistent environment
  • ❌ 未确认就执行创建/删除/更新
  • ❌ 删除生产资源（除非用户明确说明“删除生产环境xxx”）
  • ❌ 在非隔离环境中使用超级管理员权限
  • ❌ 将容器沙箱用作持久化环境

Operation Workflows

操作工作流

Troubleshooting Flow (Typical)

故障排查流程（典型）

1. Clarify symptoms → worker name/time range/error type
2. query_worker_observability to pull logs/metrics
3. If build-related → workers_builds_get_build_logs
4. If page-related → get_url_screenshot to reproduce
5. Trace changes → auditlogs_by_account_id
6. Summarize: root cause + evidence + fix recommendations
1. 明确症状 → Worker名称/时间范围/错误类型
2. 调用`query_worker_observability`拉取日志/指标
3. 若与构建相关 → 调用`workers_builds_get_build_logs`
4. 若与页面相关 → 调用`get_url_screenshot`复现问题
5. 追踪变更 → 调用`auditlogs_by_account_id`
6. 总结：根因 + 证据 + 修复建议

Resource Management Flow

资源管理流程

1. accounts_list → set_active_account
2. List resources (kv_namespaces_list / r2_buckets_list / d1_databases_list)
3. Plan changes → present to user
4. Execute after confirmation
5. Verify: audit logs + observability shows no errors
1. 调用`accounts_list` → 设置活跃账户`set_active_account`
2. 列出资源（`kv_namespaces_list` / `r2_buckets_list` / `d1_databases_list`）
3. 制定变更计划 → 提交给用户
4. 确认后执行
5. 验证：审计日志 + 可观测性显示无错误

Output Format

输出格式

  • Language: English
  • Structure: Conclusion → Key data/evidence → Tool call summary → Next steps
  • Write operations: Must clearly list operations to be executed and impact scope
Example output:
✅ Investigation complete: worker `api-gateway` experienced 5xx spike between 18:00-18:30

Root cause: New code deployed threw TypeError when processing /v2/users
Evidence:
- Logs: 18:02 first occurrence of "Cannot read property 'id' of undefined"
- Audit: 18:00 user dev@example.com deployed new version
- Metrics: error_rate jumped from 0.1% to 12%

Recommendation: Roll back to previous version, or fix /v2/users handler
  • 语言：英文
  • 结构：结论 → 关键数据/证据 → 工具调用摘要 → 后续步骤
  • 写入操作：必须明确列出要执行的操作及影响范围
示例输出：
✅ 调查完成：Worker `api-gateway`在18:00-18:30期间出现5xx错误激增

根因：部署的新代码在处理/v2/users时抛出TypeError
证据：
- 日志：18:02首次出现“Cannot read property 'id' of undefined”
- 审计：18:00用户dev@example.com部署了新版本
- 指标：错误率从0.1%跃升至12%

建议：回滚到上一版本，或修复/v2/users处理逻辑

Error Handling

错误处理

SituationAction
Account not setRun 
accounts_list
→ 
set_active_account
first
Resource doesn't existVerify ID/name is correct, list available resources
Insufficient permissionsExplain required permissions, suggest checking API token scope
Observability query too longSplit into smaller time ranges, ask more specific questions
场景操作
未设置账户先运行
accounts_list
→ 
set_active_account
资源不存在验证ID/名称是否正确，列出可用资源
权限不足说明所需权限，建议检查API令牌范围
可观测性查询耗时过长拆分为更小的时间范围，询问更具体的问题

Scenario Examples

场景示例

See scenarios.md for 20 real-world development scenarios.
查看scenarios.md获取20个真实开发场景。