mcp-gdrive-cf implementation-plan.instructions.md

Implementation Plan — Run mcp-gdrive as a Remote MCP Server on Cloudflare (via MCP proxy)

Objective

Adapt the functionality of isaacphi/mcp-gdrive to run as a remote MCP server on Cloudflare Workers, reachable by any MCP client through the Cloudflare remote MCP pattern (direct, or bridged via mcp-remote). This plan directly addresses the auth / dynamic registration concerns raised in issue #19 by exposing proper OAuth endpoints and remote transport.

1. Architecture

Runtime: Cloudflare Worker exposing an MCP Server‑Sent Events (SSE) endpoint at /sse.

MCP tools (parity with mcp-gdrive):

gdrive_search → Drive files.list (query, pageToken, pageSize)

gdrive_read_file → Drive files.get?alt=media and files.export for Docs/Sheets/Slides

gsheets_read → Sheets spreadsheets.values.batchGet (or spreadsheets.get when needed)

gsheets_update_cell → Sheets spreadsheets.values.update (valueInputOption=USER_ENTERED)

Auth layers:

Client → MCP server: optional OAuth (server acts as OAuth provider for remote MCP clients). Endpoints: /authorize, /token, /register.

MCP server → Google APIs: OAuth 2.0 “Web application” flow. Tokens stored per user.

State: user token blobs in Workers KV (namespace KV_TOKENS).

Compatibility: Remote‑capable clients connect directly; local‑only clients (e.g., Claude Desktop) use mcp-remote:

{ "mcpServers": { "gdrive": { "command": "npx", "args": ["mcp-remote", "https://..workers.dev/sse"] } } }

1. Prerequisites

Cloudflare account with Workers enabled; node LTS; wrangler CLI.

Google Cloud project with Drive API and Sheets API enabled; OAuth consent configured.

OAuth scopes: https://www.googleapis.com/auth/drive.readonly, https://www.googleapis.com/auth/spreadsheets.

1. Scaffold the Remote MCP Server

Start from Cloudflare’s remote MCP template (authless)

npm create cloudflare@latest -- my-mcp-server
--template=cloudflare/ai/demos/remote-mcp-authless cd my-mcp-server npm start # local dev at http://localhost:8788/sse npx wrangler@latest deploy

(Optional but recommended) Spin a second project using the GitHub OAuth template to see a working auth’d remote MCP, then port the auth pattern to your gdrive server:

npm create cloudflare@latest -- my-mcp-server-github-auth
--template=cloudflare/ai/demos/remote-mcp-github-oauth

This shows how the server wires OAuth + Dynamic Client Registration with SSE at /sse and auth endpoints (/authorize, /token, /register).

1. Project Layout

/src index.ts # routes: /sse, /google/authorize, /google/callback; wires OAuth provider mcp.ts # tool registry + router (gdrive + gsheets) google.ts # Google REST helpers (Drive/Sheets) auth-google.ts # OAuth URL builder, token exchange, refresh storage.ts # KV helpers (get/set user tokens) wrangler.toml # KV bindings, vars, routes bindings.d.ts # Env types for KV + secrets README.md # quickstart + client config (mcp-remote)

1. Google OAuth (server → Google)

Create OAuth Client: type Web application. Redirect URI: https://..workers.dev/google/callback (plus a localhost variant for dev if needed).

Server endpoints:

GET /google/authorize → redirect user to Google with Drive/Sheets scopes.

GET /google/callback → exchange code for {access_token, refresh_token, expiry}; persist to KV under the authenticated user.

Token storage: KV key user:: -> { google: { refresh_token, access_token, expiry, scopes } }.

Refresh: On 401 from Google APIs, auto‑refresh using the stored refresh_token and update KV.

For early iterations, you can skip client OAuth entirely and only run the Google OAuth flow the first time a user calls a tool; maintain a signed session cookie or URL parameter to correlate the token set with the client identity.

1. Client Authentication (optional now, recommended soon)

Enable OAuth for clients connecting to your MCP server, so remote clients can discover /authorize, perform dynamic client registration at /register, and obtain access tokens from /token. Use the pattern from the Cloudflare OAuth template: