GDrive MCP by Peter Garety

A Model Context Protocol (MCP) server that provides AI assistants with secure access to your Google Docs. Run it locally for personal use or deploy it to Cloudflare Workers for global scale.

✨ Key Features

• 📖 Read Google Docs content and metadata
• ✏️ Create and Update documents
• 🎨 Rich Formatting - character/paragraph styles, lists, tables, and inline images
• 📤 Export Files - Markdown, text, PDF, and DOCX as MCP embedded resources
• 🔍 Search through your documents
• 📑 Tab Detection - identify tabs in multi-tab documents
• 📋 Heading Extraction - extract document structure (H1-H6)
• 📄 Content Retrieval - get content under specific headings
• 🔐 Dual Authentication - Service Account (local) + OAuth (cloud)
• ☁️ Cloudflare Workers deployment ready
• 🖥️ Local stdio transport for Cursor and Claude Desktop
• 🚀 Fast and Scalable serverless architecture
• 🛡️ Type-safe TypeScript implementation

🛠️ Available Tools

📝 Usage Notes

• Listing, search, and metadata (`list_documents`, `search_documents`, `get_document_info`) return JSON serialized as a string in the result's single text item, content[0].text. Parse it with JSON.parse; these tools don't use MCP structuredContent.
• Each document includes id, name, mimeType, createdTime, modifiedTime, webViewLink, and, when Drive reports them, size and parents. Fields with no value are omitted rather than null.
• get_document_info returns one document object.
• list_documents returns { documents, count, nextPageToken? }.
• search_documents returns { query, documents, count, nextPageToken? }, where query echoes your search text as sent.
• count is the number of documents on this page, not the total number of matches. To get the next page, call again with the same arguments plus pageToken. nextPageToken is absent on the last page, and a page can be empty while still carrying a token.
• Section replacement (`replace_section`) previews by default. To apply, pass dryRun: false with the requiredRevisionId from your latest read. The replacement covers everything under the heading, including subheadings, and is written as plain text, so existing formatting is not preserved.
• Formatting (`update_document`) writes immediately; there is no preview mode. Positions are UTF-16 indices. Pass the requiredRevisionId from your read so edits are rejected if the document changed in the meantime.
• Multi-tab documents: pass a tabId (from get_document_tabs) for any write.
• Exports (`export_document`) return JSON metadata (filename, MIME type, byte length, SHA-256 checksum) plus one embedded resource containing the file: text for Markdown and plain text, base64 for PDF and DOCX. There is no download URL. The default size limit is 2 MiB, and exports cover the whole document (no per-tab selection). beast-scripts/save-export.mjs verifies an export and saves it to disk without overwriting existing files.

🚀 Quick Start

Choose your deployment method - these are two completely separate approaches:

🖥️ Local MCP Server (Personal Google Workspace)

Use this if: You're a Google Workspace admin and want local stdio transport. Prerequisites: Google Workspace admin access for domain-wide delegation.

1. Clone and Install

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

1. Setup Google Workspace Service Account

• Create a service account in Google Cloud Console
• Download the service account JSON key
• Configure domain-wide delegation in Google Admin Console
• See detailed setup steps below

1. Setup Environment

   cp env.example .env
   # Edit .env and add:
   # GOOGLE_SERVICE_ACCOUNT_PATH=/absolute/path/to/service-account.json
   # [email protected]

1. Build and Run

   npm run build:mcp
   npm run start:mcp

1. Configure Cursor Desktop

Add to your ~/.cursor/mcp.json:

   {
     "mcpServers": {
       "gdrive": {
         "command": "node",
         "args": ["/absolute/path/to/gdrive-mcp/dist/mcp-server.js"],
         "cwd": "/absolute/path/to/gdrive-mcp"
       }
     }
   }

☁️ Cloudflare Workers (Web-based OAuth)

Use this if: You want web-based authentication that works with any Google account. Benefits: No Workspace admin required, works with personal Gmail, scalable.

1. Setup Cloudflare

   npm install -g wrangler
   wrangler login

1. Create KV Namespaces

   npx wrangler kv namespace create "TOKEN_STORE"
   npx wrangler kv namespace create "CACHE"
   # Update wrangler.toml with the returned namespace IDs

1. Configure wrangler.toml

   cp wrangler.toml.example wrangler.toml
   # Edit wrangler.toml and update:
   # - Replace "your-gdrive-mcp-server" with your desired worker name
   # - Update GOOGLE_REDIRECT_URI placeholder
   # - Add the KV namespace IDs from step 2

1. Generate TypeScript Types

   npx wrangler types

This creates worker-configuration.d.ts with proper TypeScript types for your Cloudflare environment.

1. Initial Deploy (to get worker URL)

   npm run build
   npx wrangler deploy

Note the worker URL (e.g., https://gdrive-mcp-server.your-subdomain.workers.dev)

1. Update Configuration

• Update GOOGLE_REDIRECT_URI in wrangler.toml with your actual worker URL
• Configure Google OAuth in Cloud Console with the real callback URL (see OAuth setup instructions)

1. Set OAuth Secrets

   npx wrangler secret put GOOGLE_CLIENT_ID
   npx wrangler secret put GOOGLE_CLIENT_SECRET

1. Final Deploy

   npm run build
   npx wrangler deploy

1. Get Your API Key

Visit https://your-worker-url/ to authenticate and get your API key for MCP clients.

1. Add to MCP Client Configuration

Add the following to your ~/.cursor/mcp.json file:

   {
     "mcpServers": {
       "gdriveCF": {
         "url": "https://your-worker-url/mcp",
         "headers": {
           "Authorization": "Bearer YOUR_API_KEY_FROM_STEP_9"
         }
       }
     }
   }

Replace:

• your-worker-url with your actual worker URL
• YOUR_API_KEY_FROM_STEP_9 with the API key from the previous step.

Restart Cursor and you can now use @gdriveCF commands!

🔧 Google Workspace Setup

For Local MCP (Service Account with Domain-wide Delegation)

Prerequisites: You must be a Google Workspace admin for your domain.

1. Create Project and Enable APIs

1. Go to Google Cloud Console
2. Create a new project or select existing one
3. Enable these APIs:

• Google Docs API
• Google Drive API

2. Create Service Account

1. Go to IAM & Admin > Service Accounts
2. Click Create Service Account
3. Fill in details:

• Name: gdrive-mcp-server
• Description: Service account for Google Docs MCP server

1. Click Create and Continue
2. Skip role assignment (not needed for domain-wide delegation)
3. Click Done

3. Generate Service Account Key

1. Click on your newly created service account
2. Go to Keys tab
3. Click Add Key > Create new key
4. Choose JSON format
5. Download the JSON file and save it securely (e.g., service-account.json)

4. Configure Domain-wide Delegation

#### Step A: Note the Client ID (Google Cloud Console)

1. In your service account details, copy the Client ID

#### Step B: Authorize Service Account (Google Admin Console)

Important: You must be a Google Workspace admin for this step.

1. Go to Google Admin Console
2. Click Add new
3. Enter the Client ID from Step A
4. In OAuth scopes, enter exactly:

   https://www.googleapis.com/auth/documents,https://www.googleapis.com/auth/drive

⚠️ Critical: No spaces after the comma, exact URLs as shown

1. Click Authorize
2. Wait 5-10 minutes for changes to propagate

For Cloudflare Workers (OAuth 2.0)

1. Configure OAuth Consent Screen

1. Go to APIs & Services > OAuth consent screen
2. Choose External user type
3. Fill required fields:

• App name: "GDrive MCP Server"
• User support email: your email
• Developer contact: your email

1. Add scopes:

• https://www.googleapis.com/auth/documents
• https://www.googleapis.com/auth/drive.readonly
• openid, profile, email

These are the scopes requested by the Worker code. Local service-account authorization above separately requests documents + drive.

2. Create OAuth Credentials

1. Go to APIs & Services > Credentials
2. Click Create Credentials > OAuth 2.0 Client IDs
3. Application type: Web application
4. Name: "GDrive MCP Server"
5. Authorized redirect URIs:

• https://your-worker.workers.dev/callback (replace with your actual worker URL)

🔐 Authentication Flow

Local MCP Server

1. Service Account: Uses JSON key file for authentication
2. Domain-wide Delegation: Impersonates your Google Workspace user
3. Direct API Access: No OAuth needed, direct API calls
4. Stdio Transport: Communicates with Cursor or Claude via stdin/stdout

Cloudflare Workers

1. Web OAuth: User authenticates via /auth endpoint once
2. Token Storage: Access/refresh tokens stored in Cloudflare KV
3. API Key: Long-lived API key for MCP client authentication
4. Auto Refresh: Worker automatically refreshes Google tokens
5. HTTPS Transport: MCP client connects via HTTPS with API key

🐛 Troubleshooting

Common Issues

"OAuth Error: redirect_uri_mismatch"

• Ensure redirect URI in Google Console exactly matches your worker URL
• Example: https://gdrive-mcp-server.your-subdomain.workers.dev/callback

"Tools not found" in Cursor

• Verify your ~/.cursor/mcp.json file is correct
• Check that absolute paths are used in the configuration
• Restart Cursor after making configuration changes
• Test the MCP server manually: echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | npm run start:mcp

Build errors

• Use npm run build:mcp for local development (not npm run build)

"Unauthorized_client" error with service account

• Verify domain-wide delegation is configured in Google Admin Console
• Check that OAuth scopes are exactly: https://www.googleapis.com/auth/documents,https://www.googleapis.com/auth/drive
• Ensure GOOGLE_USER_EMAIL matches your Google Workspace domain
• Wait 5-10 minutes after configuring domain-wide delegation

"Service account authentication failed"

• Check that GOOGLE_SERVICE_ACCOUNT_PATH points to the correct JSON file
• Verify the service account JSON file is valid
• Ensure you're a Google Workspace admin (domain-wide delegation requires admin access)

🔒 Security Features

• Service Account Authentication: Secure authentication with Google Workspace
• Domain-wide Delegation: Admin-controlled access to organizational docs
• Token Management: Secure handling of authentication tokens
• Input Validation: All inputs validated and sanitized
• Minimal Permissions: Only requests necessary Google API scopes

📊 Performance Features

• Large Document Handling: Automatic chunking and streaming for big docs
• Request Timeouts: Prevents hanging requests
• Memory Management: Size limits and safe processing
• Error Recovery: Graceful handling of API failures

💡 Use Cases

• Documentation Management: AI-powered document creation and updates
• Content Analysis: Extract insights from document collections
• Automated Reporting: Generate reports directly in Google Docs
• Research Assistant: AI help with document research and organization
• Project Management: Update project docs with status and progress
• Meeting Notes: AI-assisted note-taking and document updates

🔗 Related Projects

• Model Context Protocol
• MCP SDK
• Claude Desktop
• Cloudflare Workers
• Google Docs API

📄 License

MIT License - see LICENSE file for details.