Personal Google Drive — Remote MCP Server

A production-style remote Model Context Protocol (MCP) server that connects an MCP-compatible AI assistant to a Google Drive account. It runs serverlessly on Cloudflare Workers, authenticates users with Google OAuth 2.0, and exposes Drive as a small set of safe, well-typed tools the assistant can call.

The interesting part is the auth: this single Worker is both an OAuth server and an OAuth client at the same time. It issues tokens to the AI client and logs the user into Google — a pattern that shows up in almost every real "connect my app to a third-party API on the user's behalf" integration.

New here? Read the two guides in docs/:

• docs/SETUP_GUIDE.md — build and deploy it yourself, step by step.
• docs/HOW_IT_WORKS.md — the concepts (MCP, OAuth, serverless) explained from scratch.

---

What it does

Once connected, the assistant gains these tools:

Tool	What it does
whoami	Reports which Google account is connected (a quick sanity check).
list_files	Lists the most recently modified files.
search_files	Searches by file name or full-text content.
read_file	Reads a file by id. Google Docs/Sheets/Slides are exported to text/CSV.
create_file	Creates a new file from text — including native Google Docs.
update_file	Replaces a file's contents and/or renames it.
delete_file	Moves a file to the Drive trash (recoverable, not a hard delete).

Each tool is a thin, validated wrapper over the Google Drive REST API, called with the signed-in user's access token.

Architecture at a glance

                  OAuth server                          OAuth client
   ┌───────────┐  (issues tokens)   ┌──────────────┐   (logs you in)   ┌─────────┐
   │ AI client │ ◀────────────────▶ │  This Worker │ ◀───────────────▶ │ Google  │
   └───────────┘   MCP over /sse    └──────────────┘    Drive API      └─────────┘
                                           │
                                    ┌──────┴───────┐
                                    │ Durable Obj  │  holds the live MCP session
                                    │ + KV (grants)│  stores OAuth grants/tokens
                                    └──────────────┘

1. The AI client connects to /sse, finds it protected, and runs an OAuth flow against this Worker.
2. The Worker shows a one-time approval screen, then redirects the user to Google to sign in and consent.
3. Google redirects back to /callback; the Worker exchanges the code for a Google access token and stores it (with the user's name/email) as encrypted session state.
4. The MCP tools call the Google Drive API using that token, on the user's behalf.

Tech stack

• Cloudflare Workers — serverless runtime (deploys globally, scales to zero, free tier).
• Durable Objects — host the stateful MCP session.
• Workers KV — stores OAuth grants.
• @cloudflare/workers-oauth-provider — turns the Worker into a spec-compliant OAuth server.
• agents / McpAgent — the MCP server framework.
• @modelcontextprotocol/sdk — the MCP types and server.
• Hono — tiny router for the /authorize and /callback endpoints.
• Zod — runtime validation of every tool's inputs.
• TypeScript throughout.

Repository map

File	Responsibility
src/index.ts	The MCP server, all Drive tools, and the OAuthProvider wiring.
src/google-handler.ts	The /authorize + /callback routes that talk to Google.
src/utils.ts	Google authorize-URL builder and authorization-code → token exchange.
src/workers-oauth-utils.ts	Signed-cookie approval dialog (reference helper).
wrangler.jsonc	Worker config: bindings, Durable Object, KV namespace.

Quick start

Full instructions live in docs/SETUP_GUIDE.md. The short version:

npm install
npx wrangler login
npx wrangler kv namespace create OAUTH_KV     # paste the id into wrangler.jsonc

npx wrangler secret put GOOGLE_CLIENT_ID
npx wrangler secret put GOOGLE_CLIENT_SECRET
npx wrangler secret put COOKIE_ENCRYPTION_KEY # value: openssl rand -hex 32

npm run deploy

Then add the printed https://<your-worker>.workers.dev/sse URL as a custom connector in any MCP-compatible client and sign in with Google.

Local development

cp .dev.vars.example .dev.vars   # fill in the three values
npm run dev                       # http://localhost:8788
npx @modelcontextprotocol/inspector@latest   # point it at http://localhost:8788/sse

Design notes & limitations

• Scope is configurable. The default requests the full drive scope so the write tools work. Narrow it to drive.file (only files this app creates) or drive.readonly in src/google-handler.ts to reduce risk.
• Token lifetime. Uses Google's short-lived access token (no refresh token yet), so a periodic re-connect is needed. Adding offline/refresh-token support is the natural next enhancement.
• read_file handles text. Plain-text files and exportable Google formats (Docs/Sheets/Slides) work; arbitrary binary files are out of scope.
• delete_file trashes, it doesn't purge. Files go to Drive trash and remain recoverable.

License

MIT