Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/XxYouDeaDPunKxX/cloudflare-r2-remote-mcp-worker/llms.txt

Use this file to discover all available pages before exploring further.

The Cloudflare R2 Remote MCP Worker turns a Cloudflare Worker into a remote Model Context Protocol (MCP) server, giving AI clients direct, authenticated access to R2 object storage. Instead of manually uploading files or scripting API calls, you can ask an MCP-capable client—such as ChatGPT with a custom connector—to list, read, upload, copy, or delete objects in your R2 bucket. The Worker handles GitHub OAuth, routes MCP traffic, and enforces configurable safety guards, so your storage is accessible to AI tools without being left open to the public internet.

​
Architecture overview

Every request flows through a short chain before touching R2: 
MCP client (e.g. ChatGPT)
  → GitHub OAuth  (/authorize → /callback → /token)
  → Cloudflare Worker  (/mcp)
  → R2 bucket  (via Worker binding)
The OAuth layer is provided by @cloudflare/workers-oauth-provider. When AUTH_MODE=github (the default), every MCP connection must complete a GitHub OAuth flow and the authenticated login must appear in ALLOWED_GITHUB_LOGINS. The Worker then forwards the MCP session to the server defined in src/server.ts, which registers tools against the single bound R2 bucket.
GitHub OAuth here verifies who is connecting—it does not grant any access to GitHub repositories. It is purely an identity gate.

​
Credential surfaces

Three separate credential surfaces control what operations are available. Only the Worker R2 binding is required; the other two unlock optional tool groups.
SurfaceUsed forCredential
Worker R2 bindingObject list, head, get, put, delete, copy, move, rename on the bound bucketCloudflare Worker R2 binding (set in wrangler.jsonc)
Cloudflare APIOptional read-only bucket and account visibility toolsCLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID
S3-compatible APIOptional presigned GET/PUT URL generationR2_ACCESS_KEY_ID + R2_SECRET_ACCESS_KEY

​
What is exposed

The Worker exposes object-level access to one bound R2 bucket. The default tool set covers everyday object operations:
  • Object tools — list, head, get, put, delete, copy, move, rename
  • Transfer tools — base64 upload and download for binary-safe inline transfers over MCP
Two optional tool groups can be enabled via environment variables:
  • Account/admin tools (ENABLE_ACCOUNT_TOOLS=true) — read-only visibility into bucket metadata and account configuration via the Cloudflare API
  • Presigned URL tools (ENABLE_PRESIGN_TOOLS=true) — generate time-limited presigned GET and PUT URLs using R2 S3-compatible credentials

​
What is intentionally not exposed

This project is not a full Cloudflare R2 account administration interface. The following mutating account-level operations are not available as MCP tools and are not planned:
  • Bucket creation or deletion
  • CORS rule updates
  • Lifecycle policy updates
  • Custom domain changes
  • Event notification changes
This scope boundary is intentional. Restricting the Worker to object-level operations limits blast radius if a session is ever misused.

​
Security defaults

The Worker ships with conservative defaults that you must explicitly relax:
SettingDefaultOverride
AUTH_MODEgithub (OAuth required)Set to none for local dev only
ENABLE_ACCOUNT_TOOLSfalseSet to true to enable read-only account tools
ENABLE_PRESIGN_TOOLSfalseSet to true to enable presigned URL tools
Destructive object toolsRequire confirm: true in the tool callCannot be disabled
Batch delete / move / renameSupport dryRun: true—
R2_ROOT_PREFIX"" (full bucket access)Set a prefix to restrict all operations to a subtree
Never set AUTH_MODE=none on a public-facing Worker URL unless another access control layer (such as a Cloudflare Access policy) protects the endpoint. Without auth, any MCP client that can reach the URL has full object access.

​
Worker endpoints

EndpointDescription
GET /healthzReturns ok: true plus runtime config values when the bucket is reachable. Returns 503 if the R2 binding is inaccessible.
* /mcpThe MCP endpoint consumed by AI clients. Routes through OAuth when AUTH_MODE=github.
GET /authorizeStarts the GitHub OAuth authorization flow.
GET /callbackGitHub OAuth redirect target; exchanges the code for a session.
POST /tokenOAuth token endpoint used by MCP clients after the OAuth flow completes.
POST /registerOAuth client registration endpoint.
Hit /healthz immediately after deploying or changing configuration. The response includes authMode, accountToolsEnabled, presignToolsEnabled, bucketAccessible, and active size limits—everything you need to confirm the Worker booted with the right settings.

​
Next steps

Quickstart

Deploy the Worker and connect your first AI client in minutes.

Full deployment guide

Step-by-step production deployment with all configuration options.

Authentication

Understand GitHub OAuth setup, allowed logins, and auth modes.

Tools reference

Complete reference for all MCP tools exposed by the Worker.

Build docs developers (and LLMs) love

Get started for freeTalk to us