Connect Claude Desktop, Cursor, or any MCP client to your Google Docs, Google Sheets, and Google Drive.

1. Go to the Google Cloud Console
2. Create or select a project
3. Enable the Google Docs API, Google Sheets API, and Google Drive API
4. Configure the OAuth consent screen (External, add your email as a test user)
5. Create an OAuth client ID (Desktop app type)
6. Copy the Client ID and Client Secret from the confirmation screen

Need more detail? See step-by-step instructions at the bottom of this page.

GOOGLE_CLIENT_ID="your-client-id" \
GOOGLE_CLIENT_SECRET="your-client-secret" \
npx -y @a-bonus/google-docs-mcp auth

This opens your browser for Google authorization. After you approve, the refresh token is saved to ~/.config/google-docs-mcp/token.json.

Claude Desktop / Cursor / Windsurf:

{
  "mcpServers": {
    "google-docs": {
      "command": "npx",
      "args": ["-y", "@a-bonus/google-docs-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

The server starts automatically when your MCP client needs it.

Deploy once for your team -- no local installs required. The server uses MCP OAuth 2.1 so your MCP client handles authentication automatically.

gcloud run deploy google-docs-mcp \
  --source . \
  --region europe-west3 \
  --port 8080 \
  --allow-unauthenticated \
  --set-env-vars "^|^MCP_TRANSPORT=httpStream|BASE_URL=https://your-service.run.app|GOOGLE_CLIENT_ID=...|GOOGLE_CLIENT_SECRET=...|TOKEN_STORE=firestore|JWT_SIGNING_KEY=your-secret-key"

Then each user just adds the URL to their MCP client -- no npx, no tokens, no local setup:

{
  "mcpServers": {
    "google-docs": {
      "type": "streamableHttp",
      "url": "https://your-service.run.app/mcp"
    }
  }
}

Your MCP client will prompt for Google sign-in on first connection. See Remote Deployment for details.

Tools across Google Docs, Sheets, and Drive:

"Read document ABC123 as markdown"
"Append 'Meeting notes for today' to document ABC123"
"Make the text 'Important' bold and red in document ABC123"
"Replace the entire document with this markdown: # Title\n\nNew content here"
"Insert a 3x4 table at index 50 in document ABC123"

"Read range A1:D10 from spreadsheet XYZ789"
"Write [[Name, Score], [Alice, 95], [Bob, 87]] to range A1 in spreadsheet XYZ789"
"Create a new spreadsheet titled 'Q1 Report'"
"Format row 1 as bold with a light blue background in spreadsheet XYZ789"
"Freeze the first row in spreadsheet XYZ789"
"Add a dropdown with options [Open, In Progress, Done] to range C2:C100"
"Create a table named 'Tasks' in range A1:D10 with columns: Task (TEXT), Status (DROPDOWN: 'Not Started','In Progress','Done'), Priority (NUMBER)"

"List my 10 most recent Google Docs"
"Search for documents containing 'project proposal'"
"Create a folder called 'Meeting Notes' and move document ABC123 into it"

The server supports a full round-trip markdown workflow:

1. Read a document as markdown: readDocument with format='markdown'
2. Edit the markdown locally
3. Push changes back: replaceDocumentWithMarkdown

Supported: headings, bold, italic, strikethrough, links, bullet/numbered lists, horizontal rules.

Deploy the server centrally on Google Cloud Run (or any container host) so your team can use it without local installs. The server uses MCP OAuth 2.1 with FastMCP's built-in GoogleProvider -- MCP clients handle the auth flow automatically.

Visit the server root URL (/) for setup instructions and a ready-to-copy client config.

1. Create a GCP project and enable Docs, Sheets, and Drive APIs
2. Create an OAuth client (Web application type, not Desktop)
3. Set the authorized redirect URI to {BASE_URL}/oauth/callback
4. Deploy to Cloud Run:

gcloud run deploy google-docs-mcp \
  --source . \
  --region europe-west3 \
  --port 8080 \
  --allow-unauthenticated \
  --set-env-vars "^|^MCP_TRANSPORT=httpStream|BASE_URL=https://your-service.run.app|ALLOWED_DOMAINS=yourdomain.com|GOOGLE_CLIENT_ID=...|GOOGLE_CLIENT_SECRET=...|TOKEN_STORE=firestore|JWT_SIGNING_KEY=your-secret-key"

Note: The ^|^ prefix changes the env var delimiter from , to | because ALLOWED_DOMAINS contains commas.

• By default, OAuth sessions are stored in memory and lost on restart
• For production, set TOKEN_STORE=firestore and JWT_SIGNING_KEY for persistent auth across deploys and cold starts
• ALLOWED_DOMAINS restricts access to specific Google Workspace domains
• Access tokens refresh automatically; inactive sessions expire after 30 days
• Users can revoke access at any time via Google Account permissions

Merging changes to main does not automatically update your Cloud Run service. Each deployment is independent — you need to redeploy manually when you want new features or fixes.

To update:

1. Pull the latest code:

   git pull origin main

2. Redeploy to Cloud Run:

   gcloud run deploy your-service-name --source . --region your-region

   Your existing environment variables are preserved — no need to pass --set-env-vars again.

When to redeploy:

• Bug fixes and security patches — redeploy as soon as possible
• New features — redeploy at your convenience
• Breaking changes — check the release notes before redeploying

You can check your current version against the latest release on the releases page.

Pass your Google Cloud OAuth client credentials as environment variables:

For Google Workspace with domain-wide delegation:

{
  "mcpServers": {
    "google-docs": {
      "command": "npx",
      "args": ["-y", "@a-bonus/google-docs-mcp"],
      "env": {
        "SERVICE_ACCOUNT_PATH": "/path/to/service-account-key.json",
        "GOOGLE_IMPERSONATE_USER": "user@yourdomain.com"
      }
    }
  }
}

OAuth refresh tokens are stored in ~/.config/google-docs-mcp/token.json (respects XDG_CONFIG_HOME). To re-authorize, run the auth command again or delete the token file.

Set GOOGLE_MCP_PROFILE to store tokens in a profile-specific subdirectory. This allows using different Google accounts for different projects:

{
  "mcpServers": {
    "google-docs": {
      "command": "npx",
      "args": ["-y", "@a-bonus/google-docs-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "...",
        "GOOGLE_CLIENT_SECRET": "...",
        "GOOGLE_MCP_PROFILE": "work"
      }
    }
  }
}

Tokens are stored per profile:

~/.config/google-docs-mcp/
├── token.json              # default (no profile)
├── work/token.json         # GOOGLE_MCP_PROFILE=work
├── personal/token.json     # GOOGLE_MCP_PROFILE=personal

Without GOOGLE_MCP_PROFILE, behavior is unchanged.

• Comment anchoring: Programmatically created comments appear in the comment list but aren't visibly anchored to text in the Google Docs UI. This is a Google Drive API limitation.
• Comment resolution: Resolved status may not persist in the Google Docs UI.
• Converted documents: Docs converted from Word may not support all API operations.
• Markdown tables/images: Not yet supported in the markdown-to-Docs conversion.
• Deeply nested lists: Lists with 3+ nesting levels may have formatting quirks.

• Server won't start:
  • Verify GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are set in the env block of your MCP config.
  • Try running manually: npx @a-bonus/google-docs-mcp and check stderr for errors.
• Authorization errors:
  • Ensure Docs, Sheets, and Drive APIs are enabled in Google Cloud Console.
  • Confirm your email is listed as a Test User on the OAuth consent screen.
  • Re-authorize: npx @a-bonus/google-docs-mcp auth
  • Delete ~/.config/google-docs-mcp/token.json and re-authorize if upgrading.
• Tab errors:
  • Use listTabs to see available tab IDs.
  • Omit tabId for single-tab documents.
• High CPU with multiple MCP sessions: Some clients call tools/list very often. FastMCP otherwise recomputes JSON Schema for every tool on every request, which can pin a CPU core per process. This server precomputes the payload once before stdio starts and replaces the tools/list handler with a cached snapshot. If you still see sustained load, capture a few seconds with sample <pid> 1 10 (macOS) or node --cpu-prof and report it.

Contributions are welcome! See CONTRIBUTING.md for development setup, architecture overview, and guidelines.

MIT -- see LICENSE for details.