Cloudflare R2 Remote MCP Worker

https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker
Admin
This project implements a remote Model Context Protocol (MCP) server for Cloudflare R2 on Cloudflare...
Tokens:6,482
Snippets:105
Trust Score:6.4
License:MIT
Update:4 months ago
Show doc for...
Tokens:
Raw
### Configure Worker with Example

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/README.md

Copies the example Wrangler configuration file and prompts to edit key fields like bucket names, R2 bucket name variable, and authentication mode. Do not commit the modified 'wrangler.jsonc' file.

```sh
cp wrangler.example.jsonc wrangler.jsonc
```

--------------------------------

### Install Project Dependencies and Login Wrangler

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/README.md

Installs project dependencies using npm and logs into the Wrangler CLI. Ensure Node.js 20+ and Wrangler 4 are installed beforehand.

```sh
npm install
npx wrangler login
```

--------------------------------

### GitHub OAuth App Setup

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/auth.md

Instructions for setting up a GitHub OAuth App, including the navigation path and the required Callback URL format.

```text
GitHub -> Settings -> Developer settings -> OAuth Apps -> New OAuth App
```

```text
https://<worker-url>/callback
```

```text
https://<tunnel-url>/callback
```

--------------------------------

### SDK Client List Tools Example

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/verify.md

A Node.js script demonstrating how to use the MCP SDK client to connect to the Worker and list available tools. Requires AUTH_MODE=none for local development.

```javascript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const client = new Client({ name: "r2-mcp-verify", version: "0.0.0" });
const transport = new StreamableHTTPClientTransport(new URL("http://127.0.0.1:8787/mcp"));
await client.connect(transport);
const tools = await client.listTools();
console.log(JSON.stringify(tools.tools.map((tool) => tool.name).sort(), null, 2));
await client.close();
```

--------------------------------

### Configure Local Development Variables

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/README.md

Copies the example local development environment variables file. For local development, 'AUTH_MODE=none' is used. Do not commit the '.dev.vars' file.

```sh
cp .dev.vars.example .dev.vars
```

--------------------------------

### Comma-Separated GitHub Logins Allowlist

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/auth.md

Example format for a comma-separated list of allowed GitHub logins.

```text
alice,bob,charlie
```

--------------------------------

### Presign GET URL for R2 Object

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/tools.md

Creates a temporary GET URL for an R2 object. The URL acts as bearer credentials until expiration. Enable with `ENABLE_PRESIGN_TOOLS=true`.

```json
{
  "key": "large/archive.zip",
  "expiresInSeconds": 900
}
```

--------------------------------

### Run Static Checks

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/verify.md

Installs dependencies and runs type checking and smoke tests to ensure the project compiles and contains expected public files.

```sh
npm install
npm run type-check
npm run smoke
```

--------------------------------

### Check Local Worker Health

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/verify.md

Starts the development server for the Worker and provides the local health check endpoint.

```sh
npm run dev
```

--------------------------------

### Get Text Object from R2

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/tools.md

Retrieves the content of a text-like object from R2 as UTF-8 text. Requires the object's key.

```json
{
  "key": "notes/example.txt"
}
```

--------------------------------

### Create R2 Preview Bucket

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/deploy.md

Create the R2 bucket used for local or preview Worker runs.

```sh
npx wrangler r2 bucket create your-preview-bucket-name
```

--------------------------------

### List Default Tools

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/verify.md

Lists the expected default tools available via the MCP endpoint with default feature flags.

```text
r2_download_base64
r2_object_copy
r2_object_delete
r2_object_delete_many
r2_object_get
r2_object_head
r2_object_list
r2_object_move
r2_object_put
r2_object_put_if_absent
r2_object_rename
r2_upload_base64
```

--------------------------------

### Local Authless Generic MCP Client Configuration

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/client-setup.md

Configure a generic MCP client for local development with no authentication.

```text
endpoint = http://localhost:8787/mcp
auth = none
```

--------------------------------

### Create R2 Buckets

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/README.md

Creates the primary R2 bucket and an optional preview bucket using the Wrangler CLI. Replace 'your-bucket-name' and 'your-preview-bucket-name' with your desired names.

```sh
npx wrangler r2 bucket create your-bucket-name
npx wrangler r2 bucket create your-preview-bucket-name
```

--------------------------------

### Generic MCP Client Configuration

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/client-setup.md

Configure a generic MCP client to connect to the remote service using OAuth.

```text
endpoint = https://<worker-url>/mcp
auth = OAuth
```

--------------------------------

### Create R2 Production Bucket

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/deploy.md

Create the R2 bucket that will be used by the deployed Worker.

```sh
npx wrangler r2 bucket create your-bucket-name
```

--------------------------------

### List R2 Objects

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/tools.md

Use this tool to list objects and delimited prefixes within an R2 bucket. Specify a prefix to narrow down the results and a limit for the number of items to return.

```json
{
  "prefix": "notes/",
  "limit": 20
}
```

--------------------------------

### ChatGPT Connector Configuration

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/client-setup.md

Configure your ChatGPT connector with the MCP endpoint and OAuth authentication.

```text
URL = https://<worker-url>/mcp
Auth = OAuth
```

--------------------------------

### Set Environment Variables for Auth

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/auth.md

Configuration for setting environment variables `AUTH_MODE` and `ALLOWED_GITHUB_LOGINS` within `wrangler.jsonc`.

```jsonc
"vars": {
  "AUTH_MODE": "github",
  "ALLOWED_GITHUB_LOGINS": "your-github-login"
}
```

--------------------------------

### Presign PUT URL for R2 Object

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/tools.md

Creates a temporary PUT URL for uploading to an R2 object. The URL acts as bearer credentials until expiration. Enable with `ENABLE_PRESIGN_TOOLS=true`.

```json
{
  "key": "uploads/archive.zip",
  "contentType": "application/zip",
  "expiresInSeconds": 900
}
```

--------------------------------

### Configure KV Namespace in wrangler.jsonc

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/auth.md

Configuration snippet for `wrangler.jsonc` to bind the created KV namespace to the Worker under the name `OAUTH_KV`.

```jsonc
"kv_namespaces": [
  {
    "binding": "OAUTH_KV",
    "id": "your-kv-namespace-id"
  }
]
```

--------------------------------

### Set Optional R2 Presign Tool Secrets

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/deploy.md

Set the R2 access key ID and secret access key if presign tools are to be used.

```sh
npx wrangler secret put R2_ACCESS_KEY_ID -c wrangler.jsonc
npx wrangler secret put R2_SECRET_ACCESS_KEY -c wrangler.jsonc
```

--------------------------------

### Preview Move Object in R2

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/tools.md

Performs a dry run of moving an object within R2, copying it to a new destination and then deleting the source. Requires `confirm: true` and `dryRun: true` to preview the operation.

```json
{
  "sourceKey": "notes/a.txt",
  "destinationKey": "archive/a.txt",
  "dryRun": true,
  "confirm": true
}
```

--------------------------------

### Connect to MCP Endpoint (Local Authless)

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/verify.md

Provides the local URL for connecting to the MCP endpoint during authless development.

```text
http://localhost:8787/mcp
```

--------------------------------

### Run MCP Inspector

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/verify.md

Executes the MCP Inspector tool to verify the MCP endpoint is reachable and exposes tools.

```sh
npx @modelcontextprotocol/inspector@latest
```

--------------------------------

### Download Object as Base64 from R2

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/tools.md

Returns an R2 object's bytes as a base64 encoded string. This tool is bounded by `MAX_TRANSFER_BYTES`.

```json
{
  "key": "images/example.png"
}
```

--------------------------------

### Run Type Check and Smoke Tests

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/README.md

Executes type checking and smoke tests for the Worker. These commands help verify the project's integrity and basic functionality.

```sh
npm run type-check
npm run smoke
```

--------------------------------

### Preview Batch Delete Objects in R2

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/tools.md

Allows a dry run of a batch delete operation for multiple objects in R2. This confirms the operation without actually deleting the objects, requiring `confirm: true` and `dryRun: true`.

```json
{
  "keys": ["notes/a.txt", "notes/b.txt"],
  "dryRun": true,
  "confirm": true
}
```

--------------------------------

### Configure R2 Bucket Binding

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/deploy.md

Define the R2 bucket binding in the Wrangler configuration. This allows the worker to interact with the specified R2 buckets.

```jsonc
"r2_buckets": [
  {
    "binding": "R2_BUCKET",
    "bucket_name": "your-bucket-name",
    "preview_bucket_name": "your-preview-bucket-name"
  }
]
```

--------------------------------

### Generate High-Entropy Cookie Encryption Key

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/auth.md

Command to generate a random, high-entropy base64 string suitable for use as a cookie encryption key.

```sh
openssl rand -base64 32
```

--------------------------------

### OAuth Flow Sequence

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/auth.md

This text-based diagram illustrates the sequence of requests between an MCP client, the Worker, and GitHub during the OAuth authorization process.

```text
MCP client
-> Worker /authorize
-> GitHub login
-> Worker /callback
-> allowlist check
-> MCP client receives OAuth token
-> MCP client calls /mcp
```

--------------------------------

### Create KV Namespace for OAuth State

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/auth.md

Command to create a new Cloudflare KV namespace, which will be used to store OAuth state for validation.

```sh
npx wrangler kv namespace create OAUTH_KV
```

--------------------------------

### Deploy Worker

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/README.md

Deploys the Cloudflare Worker using npm and Wrangler. This command builds and uploads the worker to Cloudflare.

```sh
npm run deploy
```

--------------------------------

### Connect to MCP Endpoint (Remote)

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/verify.md

Provides the URL for connecting to the MCP endpoint of the deployed Worker.

```text
https://<worker-url>/mcp
```

--------------------------------

### Worker Routes for OAuth

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/auth.md

This table outlines the different routes exposed by the Worker and their respective purposes within the OAuth and MCP client interaction.

```text
Route | Purpose
-- | --
/authorize | Starts OAuth authorization.
/callback | Receives GitHub OAuth callback.
/token | OAuth token endpoint for MCP clients.
/register | Dynamic client registration endpoint.
/mcp | Protected MCP endpoint.
```

--------------------------------

### Set R2 Root Prefix

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/security.md

Use R2_ROOT_PREFIX to restrict tools to a specific logical subtree within an R2 bucket. This configuration prevents access to objects outside the specified prefix.

```text
R2_ROOT_PREFIX=projects/example
```

--------------------------------

### OAuth Routes for GitHub Authentication

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/client-setup.md

These routes are used by the client when AUTH_MODE is set to github for OAuth authentication.

```text
/authorize
/token
/register
/callback
```

--------------------------------

### Set GitHub OAuth Secrets

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/auth.md

Commands to set the `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`, and `COOKIE_ENCRYPTION_KEY` as secrets for the Worker.

```sh
npx wrangler secret put GITHUB_CLIENT_ID -c wrangler.jsonc
```

```sh
npx wrangler secret put GITHUB_CLIENT_SECRET -c wrangler.jsonc
```

```sh
npx wrangler secret put COOKIE_ENCRYPTION_KEY -c wrangler.jsonc
```

--------------------------------

### Put Text Object in R2

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/tools.md

Writes UTF-8 text to an object in R2. Ensure the contentType is correctly set for the text data.

```json
{
  "key": "notes/example.txt",
  "text": "hello",
  "contentType": "text/plain"
}
```

--------------------------------

### Upload Base64 Payload to R2

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/tools.md

Uploads a base64 encoded payload to an R2 object. Ensure the `contentType` matches the data. This tool is bounded by `MAX_TRANSFER_BYTES`.

```json
{
  "key": "images/example.png",
  "contentBase64": "<base64>",
  "contentType": "image/png"
}
```

--------------------------------

### Set Optional Cloudflare API Token Secret

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/deploy.md

Set the Cloudflare API token as a secret if read-only account tools are needed.

```sh
npx wrangler secret put CLOUDFLARE_API_TOKEN -c wrangler.jsonc
```

--------------------------------

### Manage Secrets with Wrangler

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/security.md

Use Wrangler secrets to securely manage sensitive credentials for deployed applications. This prevents committing secrets directly into version control.

```sh
npx wrangler secret put CLOUDFLARE_API_TOKEN -c wrangler.jsonc
```

```sh
npx wrangler secret put GITHUB_CLIENT_ID -c wrangler.jsonc
```

```sh
npx wrangler secret put GITHUB_CLIENT_SECRET -c wrangler.jsonc
```

```sh
npx wrangler secret put COOKIE_ENCRYPTION_KEY -c wrangler.jsonc
```

```sh
npx wrangler secret put R2_ACCESS_KEY_ID -c wrangler.jsonc
```

```sh
npx wrangler secret put R2_SECRET_ACCESS_KEY -c wrangler.jsonc
```

--------------------------------

### Local Verification Health Check

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/deploy.md

Access the local health check endpoint to verify the worker and R2 bucket accessibility.

```text
http://localhost:8787/healthz
```

--------------------------------

### Local Health Check Response

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/deploy.md

Expected JSON response from the local health check endpoint, indicating successful worker and bucket access.

```json
{
  "ok": true,
  "bucketAccessible": true
}
```

--------------------------------

### Check Remote Worker Health

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/verify.md

Provides the URL for checking the health of the deployed Worker.

```text
https://<worker-url>/healthz
```

--------------------------------

### Delete Single Object from R2

Source: https://github.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/blob/main/docs/tools.md

Deletes a single object from R2. This is a destructive operation and requires confirmation.

```json
{
  "key": "notes/example.txt",
  "confirm": true
}
```
Tokens:
Raw