mcp-gdrive-cf

Remote MCP server for Google Drive and Sheets running on Cloudflare Workers with full OAuth 2.0 support.

Production Ready ✅ | 11 Tools | OAuth 2.0 | PKCE | Global Edge Network

Adapted from isaacphi/mcp-gdrive to run as a remote HTTP/SSE MCP server on Cloudflare's edge network with complete OAuth 2.0 authorization server capabilities.

---

🚀 Quick Start

```bash

1. Clone and install

git clone https://github.com/brianmoney/mcp-gdrive-cf.git cd mcp-gdrive-cf npm install

2. Create KV namespaces

wrangler kv:namespace create KV_TOKENS wrangler kv:namespace create KV_CLIENTS

3. Update wrangler.toml with your namespace IDs

4. Configure Google OAuth credentials

wrangler secret put GOOGLE_CLIENT_SECRET

5. Deploy

wrangler deploy

6. Test with MCP Inspector

npx @modelcontextprotocol/inspector https://your-worker.workers.dev/sse ```

---

✨ Features

Drive Operations

• 🔍 Search - Basic and advanced search with filters (MIME type, owner, dates, shared drives)
• 📄 Read - Read any file with 22+ export formats (PDF, DOCX, XLSX, Markdown, etc.)
• 📁 Create Folders - Organize files with nested folder structures
• ⬆️ Upload - Upload files up to 5MB
• 🗑️ Delete - Move files to trash
• 📦 Move - Reorganize files between folders
• 🔐 Share - Add permissions (reader, writer, commenter, owner)

Sheets Operations

• 📊 Read - Batch read multiple ranges
• ✏️ Update - Update individual cells
• ➕ Append - Add rows to spreadsheets

Infrastructure

• ☁️ Global Edge Network - Runs on Cloudflare Workers worldwide
• 🔐 OAuth 2.0 Server - Full authorization server with PKCE support
• 🔑 Dynamic Client Registration - Automatic client onboarding
• 🔄 Auto Token Refresh - Seamless Google token renewal
• 📡 SSE Transport - Real-time Server-Sent Events
• 🛡️ Secure - HTTPS only, encrypted token storage

---

🎯 What Makes This Different

Unlike the original STDIO-based `mcp-gdrive`, this implementation:

1. Runs remotely on Cloudflare Workers (no local process)
2. Full OAuth 2.0 authorization server (not just OAuth client)
3. Multi-client support via dynamic client registration
4. PKCE security for public clients
5. 22+ export formats for Drive files
6. Write operations (create, delete, move, share, upload)
7. Production tested with real workloads

---

📋 Prerequisites

Required

• Cloudflare Account with Workers enabled (free tier works)
• Google Cloud Project with Drive API and Sheets API enabled
• Node.js LTS (v18+)
• Wrangler CLI (`npm install -g wrangler`)

Google Cloud Setup

1. Create a project at Google Cloud Console
2. Enable APIs:
   • Google Drive API
   • Google Sheets API
3. Create OAuth 2.0 credentials:
   • Type: Web application
   • Redirect URIs: `https://your-worker.workers.dev/google/callback`
4. Required OAuth scopes:
   • `https://www.googleapis.com/auth/drive`
   • `https://www.googleapis.com/auth/spreadsheets`

---

🔧 Installation & Deployment

1. Install Dependencies

```bash npm install ```

2. Create KV Namespaces

```bash

For user session tokens

wrangler kv:namespace create KV_TOKENS

For OAuth client registrations

wrangler kv:namespace create KV_CLIENTS ```

Copy the namespace IDs to `wrangler.toml`:

```toml [[kv_namespaces]] binding = "KV_TOKENS" id = "your-tokens-namespace-id"

[[kv_namespaces]] binding = "KV_CLIENTS" id = "your-clients-namespace-id" ```

3. Configure Environment Variables

Add to `wrangler.toml`:

```toml [vars] GOOGLE_CLIENT_ID = "your-client-id.apps.googleusercontent.com" ```

Set secrets:

```bash

Google OAuth client secret

wrangler secret put GOOGLE_CLIENT_SECRET ```

4. Deploy

```bash wrangler deploy ```

Your worker will be available at: `https://your-worker-name.your-account.workers.dev`

---

🔐 OAuth 2.0 Flow

This server implements a complete OAuth 2.0 authorization server per the MCP specification.

Using MCP Inspector

The easiest way to test the OAuth flow:

```bash npx @modelcontextprotocol/inspector https://your-worker.workers.dev/sse ```

1. Discovery - Inspector auto-discovers OAuth endpoints
2. Registration - Click "Guided Setup" → registers client automatically
3. Authorization - Redirects to Google → authenticates → redirects back
4. Token Exchange - Automatically exchanges code for access token
5. Use Tools - All 11 tools now available!

Security Features

• ✅ PKCE (RFC 7636) - Proof Key for Code Exchange
• ✅ State Parameter - CSRF protection
• ✅ HTTPS Only - Enforced by Cloudflare Workers
• ✅ Secure Token Storage - Encrypted in Workers KV
• ✅ Token Expiration - Access tokens expire in 1 hour
• ✅ Client Secret Hashing - SHA-256 hashed storage
• ✅ Authorization Code Single-Use - Codes deleted after exchange

---

🛠️ Available Tools

Drive Tools

• `gdrive_search` - Basic search across all files
• `gdrive_search_advanced` - Advanced search with filters
• `gdrive_read_file` - Read files with 22+ export formats
• `gdrive_create_folder` - Create folders
• `gdrive_upload_file` - Upload files (up to 5MB)
• `gdrive_delete_file` - Move files to trash
• `gdrive_move_file` - Move files between folders
• `gdrive_add_permission` - Share files/folders

Sheets Tools

• `gsheets_read` - Read multiple ranges
• `gsheets_update_cell` - Update single cells
• `gsheets_append_row` - Append rows

---

🔌 Client Configuration

VS Code with MCP Extension

Create `.vscode/settings.json`:

```json { "mcp.servers": { "gdrive": { "url": "https://your-worker.workers.dev/sse", "authorization": { "type": "oauth2" } } } } ```

Claude Desktop / Cline

macOS/Linux: `~/Library/Application Support/Claude/claude_desktop_config.json`
Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json { "mcpServers": { "gdrive": { "url": "https://your-worker.workers.dev/sse" } } } ```

---

🧪 Testing

Local Development

```bash npm start

Server available at http://localhost:8788

```

Test with MCP Inspector

```bash npx @modelcontextprotocol/inspector http://localhost:8788/sse ```

Check CloudFlare Logs

```bash wrangler tail --format pretty ```

---

🐛 Troubleshooting

"Failed to discover OAuth metadata"

Solution:

• Ensure `/.well-known/oauth-authorization-server` returns valid JSON
• Check CORS headers are present
• Verify latest version is deployed: `wrangler deploy`

"Token exchange failed: HTTP 400"

Solutions:

• Check code_verifier matches original code_challenge
• Ensure redirect_uri exactly matches registration
• Verify client credentials are correct
• Check CloudFlare logs: `wrangler tail`

Tools not working

Solutions:

• Check Google OAuth scopes include `drive` and `spreadsheets`
• Re-authenticate if scopes changed: visit `/google/authorize`
• Verify Worker has valid Google access token
• Check KV namespace bindings in `wrangler.toml`

---

📊 Performance & Limits

Resource	Limit	Notes
Request Timeout	30 seconds	CloudFlare Workers limit
File Upload	5 MB	Simple upload API limit
File Export	10 MB	Google Drive export limit
Token Storage	30 days	Automatic cleanup
Authorization Code	10 minutes	Single-use
Access Token	1 hour	Auto-refreshed

---

🔒 Security Best Practices

1. Never commit secrets - Use `wrangler secret put`
2. Rotate client secrets - Periodically regenerate OAuth credentials
3. Monitor access - Use CloudFlare Analytics to track usage
4. Limit OAuth scopes - Only request necessary Google permissions
5. Use PKCE - Always use PKCE for public clients
6. Validate redirect URIs - Whitelist exact URIs in Google Console
7. Enable 2FA - Protect your CloudFlare and Google accounts

---

📄 License

MIT License

---

🙏 Acknowledgments

• isaacphi/mcp-gdrive - Original STDIO implementation
• Model Context Protocol - MCP specification
• CloudFlare Workers - Serverless platform

---

Made with ☁️ by Brian Money