google-docs-mcp MCP工具

Remote Deployment (Cloud Run)

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.

---

Remote Deployment

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.

Setup

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.

Updating Your Deployment

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
   

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.

---

Google Cloud Setup Details

<details> <summary>Step-by-step Google Cloud Console instructions</summary>

For remote deployment, create an OAuth client of type Web application (not Desktop app). Use Desktop app only for local stdio usage.

1. Go to Google Cloud Console: Open console.cloud.google.com 2. Create or Select a Project: Click the project dropdown > "NEW PROJECT". Name it (e.g., "MCP Docs Server") and click "CREATE". 3. Enable APIs: - Navigate to "APIs & Services" > "Library" - Search for and enable: Google Docs API, Google Sheets API, Google Drive API, Gmail API, Google Calendar API 4. Configure OAuth Consent Screen: - Go to "APIs & Services" > "OAuth consent screen" - Choose "External" and click "CREATE" - Fill in: App name, User support email, Developer contact email - Click "SAVE AND CONTINUE" - Add scopes: documents, spreadsheets, drive, gmail.modify, calendar.events - Click "SAVE AND CONTINUE" - Add your Google email as a Test User - Click "SAVE AND CONTINUE" 5. Create Credentials: - Go to "APIs & Services" > "Credentials" - Click "+ CREATE CREDENTIALS" > "OAuth client ID" - Application type: "Desktop app" - Click "CREATE" - Copy the Client ID and Client Secret

</details>

---

Quick Start

Usage Examples

Environment Variables

Authentication Options

Markdown Workflow

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.

Troubleshooting

• 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, Drive, Gmail, and Calendar APIs are enabled in Google Cloud Console.
• Confirm your email is listed as a Test User on the OAuth consent screen and that all required scopes (Docs, Sheets, Drive, gmail.modify, calendar.events) are added to the consent screen.
• Re-authorize: npx @a-bonus/google-docs-mcp auth
• Delete ~/.config/google-docs-mcp/token.json and re-authorize if upgrading — Gmail and Calendar scopes were added in later versions, so existing tokens must be refreshed.
• Remote (Cloud Run) users must sign out and sign back in from their MCP client so Google reissues consent with the new scope list.
• Tab errors:
• Use listTabs to see available tab IDs.
• Omit tabId for single-tab documents.
• "Page not found" on claude.ai during OAuth sign-in (remote deployments):
• Symptom: clicking Connect on a custom MCP connector lands on the Claude "Page not found" page instead of the Google sign-in screen.
• Cause: Cloud Run cold start. The first request to an idle service times out before the container finishes spinning up, and Claude routes the failed redirect to its 404 page.
• Workaround: hard-refresh the page (Cmd+Shift+R on macOS, Ctrl+Shift+R on Windows/Linux). The second request hits a now-warm instance and the OAuth flow proceeds normally.
• Permanent fix: set --min-instances=1 on your Cloud Run service to keep one instance always warm (gcloud run services update <service> --region <region> --min-instances=1). Costs ~$2–3/month for the memory reservation.
• Re-authenticated unexpectedly after a redeploy (remote deployments):
• Cause: JWT_SIGNING_KEY is auto-generated on each container start, so redeploys invalidate all previously issued sessions.
• Fix: set a stable JWT_SIGNING_KEY env var on the Cloud Run service so it survives restarts: gcloud run services update <service> --region <region> --update-env-vars JWT_SIGNING_KEY=$(openssl rand -hex 32). Sessions minted after this change will survive future redeploys.
• 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.

---