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
                                    └──────────────┘

The AI client connects to /sse, finds it protected, and runs an OAuth flow against this Worker.
The Worker shows a one-time approval screen, then redirects the user to Google to sign in and consent.
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.
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