Cloudflare R2 MCP 完整設定教學

[Aiko]

Cloudflare R2 MCP 完整設定教學

最熱門的 MCP Repo 比較

Repo	類型	Stars	R2 支援	推薦度
cloudflare/mcp	官方遠端 MCP (Code Mode)	280+	涵蓋全部 2,500+ API
cloudflare/mcp-server-cloudflare	官方舊版（產品分拆版）	2.3k+	獨立 R2 tools
smithery-ai/mcp-server-cloudflare-1	社群 fork	較少	明確 R2 工具

結論：推薦使用 cloudflare/mcp（官方最新版），只需 2 個 tool（search() + execute()）就能存取整個 Cloudflare API，包含 R2 的所有操作，token 消耗僅 ~1,000 tokens。

---

方案 A：官方 Cloudflare MCP（推薦 ）

優勢

• OAuth 認證，不需要手動管理 API Token
• 涵蓋 R2、Workers、D1、KV、DNS 等全部服務
• 只用 ~1,000 tokens，不佔用 context window

步驟 1：Claude Code 一鍵安裝

# 全域安裝（所有專案都能用）
claude mcp add --transport http --scope user cloudflare-api https://mcp.cloudflare.com/mcp

或者只在當前專案使用：

# 專案層級安裝
claude mcp add --transport http --scope local cloudflare-api https://mcp.cloudflare.com/mcp

步驟 2：OAuth 授權

首次使用時，Claude Code 會自動打開瀏覽器進行 Cloudflare OAuth 登入：

1. 瀏覽器自動跳出 Cloudflare 授權頁面
2. 登入你的 Cloudflare 帳號
3. 選擇授權範圍 — 請勾選以下權限：
   • Account — Read
   • Workers R2 Storage — Edit（這是 R2 上傳/刪除的關鍵權限）
4. 點擊 Authorize
5. 回到 Claude Code 會顯示 Connected 訊息

步驟 3：驗證連線

# 在 Claude Code 中執行
/mcp

應該會看到 cloudflare-api 顯示為 connected，帶有 search 和 execute 兩個 tools。

步驟 4：R2 操作範例

在 Claude Code 中直接用自然語言操作：

# 列出所有 R2 buckets
「列出我的所有 R2 buckets」

# 建立新 bucket
「建立一個叫做 my-assets 的 R2 bucket」

# 上傳檔案
「上傳 ./image.png 到 R2 bucket my-assets 的 images/ 路徑下」

# 列出 bucket 中的物件
「列出 my-assets bucket 中所有的物件」

---

方案 B：使用 API Token + 舊版 MCP Server（離線 / CI/CD 用）

如果你需要在 CI/CD 環境或無法進行 OAuth 的場景使用，可以手動建立 API Token。

步驟 1：建立 Cloudflare R2 API Token

1. 登入 Cloudflare Dashboard
2. 左側選單進入 R2 Object Storage → Overview
3. 右側找到 Account Details 區塊，記下你的 Account ID
4. 點擊 Manage R2 API Tokens（在 Account Details 區塊中的 {} 按鈕）
5. 點擊 Create API token
6. 設定 Token：

欄位	建議值
Token Name	claude-code-r2
Permissions	Object Read & Write
Specify Bucket(s)	選擇特定 bucket 或 All buckets
TTL	Forever（或依需求設定）

7. 點擊 Create API Token
8. 立即複製並保存以下資訊（Secret Key 只會顯示一次）：
   • Access Key ID
   • Secret Access Key

步驟 2：記下你的 S3 Endpoint

https://<YOUR_ACCOUNT_ID>.r2.cloudflarestorage.com

你的 Account ID 可以在 Dashboard URL 或 R2 Overview 頁面的右側找到。

步驟 3：安裝舊版 MCP Server（含明確 R2 工具）

# Claude Code 安裝 cloudflare/mcp-server-cloudflare（舊版，有獨立 R2 tools）
claude mcp add cloudflare-r2 \
  -e CLOUDFLARE_ACCOUNT_ID=你的AccountID \
  -e CLOUDFLARE_API_TOKEN=你的APIToken \
  -- npx -y @cloudflare/mcp-server-cloudflare

步驟 4：驗證 R2 工具

/mcp

你應該會看到以下 R2 相關工具：

• r2_list_buckets — 列出所有 buckets
• r2_create_bucket — 建立 bucket
• r2_delete_bucket — 刪除 bucket
• r2_list_objects — 列出 bucket 內物件
• r2_get_object — 取得物件
• r2_put_object — 上傳物件
• r2_delete_object — 刪除物件

---

一鍵設定腳本（複製貼上即可）

方案 A（推薦）— 官方遠端 OAuth MCP

claude mcp add --transport http --scope user cloudflare-api https://mcp.cloudflare.com/mcp

完成後重啟 Claude Code，首次使用時會自動跳出 OAuth 授權。

方案 B — API Token + 舊版 MCP

# ⚠️ 請先替換下面三個變數
export CF_ACCOUNT_ID="你的_ACCOUNT_ID"
export CF_API_TOKEN="你的_API_TOKEN"

# 安裝 MCP Server
claude mcp add cloudflare-r2 \
  -e CLOUDFLARE_ACCOUNT_ID=$CF_ACCOUNT_ID \
  -e CLOUDFLARE_API_TOKEN=$CF_API_TOKEN \
  -- npx -y @cloudflare/mcp-server-cloudflare

方案 C — 直接寫入 .mcp.json（專案根目錄）

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

或用 API Token 的舊版：

{
  "mcpServers": {
    "cloudflare-r2": {
      "command": "npx",
      "args": ["-y", "@cloudflare/mcp-server-cloudflare"],
      "env": {
        "CLOUDFLARE_ACCOUNT_ID": "你的_ACCOUNT_ID",
        "CLOUDFLARE_API_TOKEN": "你的_API_TOKEN"
      }
    }
  }
}

---

建立 Cloudflare API Token 完整流程圖

Cloudflare Dashboard
  └── R2 Object Storage → Overview
       ├── 右側 Account Details → 複製 Account ID
       └── 點擊 {} Manage R2 API Tokens
            └── Create API Token
                 ├── Token Name: claude-code-r2
                 ├── Permissions: Object Read & Write
                 ├── Bucket Scope: 選 All 或特定 bucket
                 └── Create → 複製 Access Key ID + Secret Access Key

---

常見問題

Q: OAuth 授權後跳回 Claude Code 但顯示失敗？

重新執行 /mcp，如果還是失敗，刪除快取後重試：

rm -rf ~/.mcp-auth/
claude mcp remove cloudflare-api
claude mcp add --transport http --scope user cloudflare-api https://mcp.cloudflare.com/mcp

Q: WSL 環境無法自動開啟瀏覽器？

在 MCP 啟動腳本中加入 export BROWSER=wslview。

Q: 用方案 B 但 r2_put_object 失敗？

確認你的 API Token 權限是 Object Read & Write，不是 Read only。

Q: 要怎麼上傳大檔案到 R2？

MCP 的 r2_put_object 適合小型文字/JSON 檔案。大型檔案建議用 S3 SDK：

# 使用 AWS CLI（R2 是 S3 相容的）
aws s3 cp ./large-file.zip s3://my-bucket/path/ \
  --endpoint-url https://ACCOUNT_ID.r2.cloudflarestorage.com

---

參考連結

• 官方 MCP Server：GitHub - cloudflare/mcp: MCP server for the Cloudflare API · GitHub
• 舊版 MCP Server：GitHub - cloudflare/mcp-server-cloudflare · GitHub
• R2 API Token 文件：Authentication · Cloudflare R2 docs
• Cloudflare MCP 文件：Cloudflare's own MCP servers · Cloudflare Agents docs
• Claude Code MCP 設定：Connect Claude Code to tools via MCP - Claude Code Docs