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.

Cloudflare R2 Remote MCP Worker is a Cloudflare Worker that wraps your R2 bucket as a fully remote Model Context Protocol (MCP) server. MCP clients — such as ChatGPT custom connectors or MCP Inspector — authenticate through GitHub OAuth, then interact with your R2 bucket using structured tool calls. Object operations (list, get, put, delete, copy, move, rename) are enabled by default. Optional read-only account visibility tools and presigned URL tools can be unlocked through environment variables, each backed by its own credential surface.
This project exposes object-level access to one bound R2 bucket. Mutating account operations — such as bucket creation, CORS updates, lifecycle configuration, and domain changes — are intentionally not exposed as MCP tools.

​
How It Works

Every request follows this path: 
MCP client (e.g. ChatGPT / MCP Inspector)
  └─► GitHub OAuth  (/authorize → /callback → /token)
        └─► Cloudflare Worker  (/mcp)
              └─► R2 bucket  (bound via R2_BUCKET binding)
When AUTH_MODE=github (the production default), the OAuth provider intercepts calls to /mcp and enforces GitHub login before forwarding authenticated requests to the MCP handler. When AUTH_MODE=none (local development only), requests reach the MCP handler directly with no authentication gate.

​
Credential Surfaces

The Worker exposes three independent credential surfaces. Each controls a distinct group of tools.
SurfaceToolsCredentials required
Worker R2 bindingObject list, head, get, put, delete, copy, move, rename; base64 upload/downloadR2 binding in wrangler.jsonc (always present)
Cloudflare APIRead-only bucket and account visibilityCLOUDFLARE_ACCOUNT_ID + CLOUDFLARE_API_TOKEN (read-only token)
R2 S3-compatible APIPresigned GET and PUT URLsR2_ACCESS_KEY_ID + R2_SECRET_ACCESS_KEY

​
Key Features

Remote MCP Server

Exposes a standards-compliant MCP endpoint at /mcp, compatible with any MCP client that supports remote servers and OAuth.

GitHub OAuth Protection

Restricts access to a configurable allowlist of GitHub logins via ALLOWED_GITHUB_LOGINS. OAuth state is stored in a KV namespace.

Object-Level R2 Tools

Full object lifecycle: list, head, get, put, delete, copy, move, and rename inside the bound bucket. Destructive operations require confirm: true.

Base64 Transfer Tools

Upload and download binary or text objects encoded as base64 via r2_upload_base64 and r2_download_base64, up to the configurable MAX_TRANSFER_BYTES limit (default 1 MB).

Optional Account Tools

Read-only bucket and account metadata tools, enabled with ENABLE_ACCOUNT_TOOLS=true. Requires a Cloudflare API token.

Optional Presigned URLs

Generate time-limited presigned GET and PUT URLs for direct client access, enabled with ENABLE_PRESIGN_TOOLS=true. Uses R2 S3 credentials.

Prefix Isolation

Set R2_ROOT_PREFIX to restrict all object operations to a single key prefix, preventing access to the rest of the bucket.

Health Endpoint

/healthz verifies bucket accessibility and returns current runtime configuration including enabled tool surfaces and auth mode.

​
Tool Surfaces

​
Default-enabled tools

The following tools are registered on every deployment without any additional configuration:
  • Object tools — r2_object_list, r2_object_head, r2_object_get, r2_object_put, r2_object_put_if_absent, r2_object_delete, r2_object_delete_many, r2_object_copy, r2_object_move, r2_object_rename
  • Base64 tools — r2_upload_base64, r2_download_base64

​
Optional tools

VariableDefaultEffect
ENABLE_ACCOUNT_TOOLS=truefalseRegisters read-only Cloudflare account and bucket metadata tools. Requires CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN.
ENABLE_PRESIGN_TOOLS=truefalseRegisters presigned URL generation tools. Requires R2_ACCESS_KEY_ID and R2_SECRET_ACCESS_KEY.
Account tools are strictly read-only. No tool exposed by this Worker performs mutating account operations such as creating buckets, modifying CORS, or changing lifecycle rules.

​
Security Defaults

  • AUTH_MODE defaults to "github" when the variable is absent or empty.
  • Account and presigned URL tools are disabled by default and must be explicitly opted into.
  • Destructive object operations (r2_object_delete, batch operations) require a confirm: true argument.
  • Batch delete, move, and rename operations support dryRun: true for safe previewing.
  • R2_ROOT_PREFIX can isolate all object operations to a single prefix.

​
Prerequisites

Before deploying, make sure you have the following ready:

Node.js 20+

The project uses ES modules and requires Node.js 20 or newer. Check with node --version.

Wrangler 4

The Cloudflare Workers CLI. Installed as a dev dependency; use npx wrangler or npm run deploy.

Cloudflare Account

A Cloudflare account with Workers and R2 enabled. R2 has a free tier with a generous monthly allowance.

R2 Bucket

At least one R2 bucket for production and one for Wrangler preview environments (used in local wrangler dev).

GitHub OAuth App

Required for public deployments (AUTH_MODE=github). Provides the client ID, client secret, and callback URL.

MCP Client

Any MCP-compatible client: ChatGPT custom MCP connector, MCP Inspector, or a custom integration using the MCP SDK.

Build docs developers (and LLMs) love

Get started for freeTalk to us