Google Workspace MCP 服务

gdoc-mcp

An MCP server that lets Claude read and edit Google Docs, Sheets, Calendar, and Gmail using markdown syntax.

Features

Google Docs

• Read documents as markdown (bold, italic, underline, strikethrough, links, headings, lists, tables)
• Edit text with markdown formatting (**bold**, *italic*, <u>underline</u>, ~~strikethrough~~, [link](url))
• Search with regex patterns and context
• List, create, and copy documents

Google Sheets

• Read sheets as markdown tables
• Edit cells (formulas supported)
• Append rows
• Add new sheets (tabs)
• Get sheet metadata
• Create and copy spreadsheets

Google Calendar

• List all calendars you have access to (owned, shared, subscribed)
• List events with date range and search filtering, across several calendars at once
• Flag possible duplicate events across calendars
• Create, update, delete, and move events between calendars
• All-day and timed events (including switching between them)
• Recurring events: create/edit RRULEs, edit or delete one/following/all occurrences, end a series on a date
• Refer to calendars by display name (e.g. "Family") or ID
• Batch several operations in one call
• Natural language event creation (e.g. "Lunch tomorrow at noon")

Gmail

• List and search emails with Gmail search syntax
• Read full message content (plain text extraction)
• Create drafts (new or reply) with optional file attachments — drafts are NOT sent
• Update and delete existing drafts
• Reply drafts thread correctly with original conversations
• List and save email attachments to local files

Concurrency Safety

• Requires read-before-edit (ensures you've seen the content)
• Text-based verification (confirms target text exists before replacing)
• Formula-aware sheet editing (detects concurrent formula changes)
• Colored diff output shows exactly what changed

Installation

npm install && npm run build

Authentication

Uses OAuth 2.0 for authentication with all Google Workspace APIs.

1. Create OAuth Credentials

1. Go to console.cloud.google.com
2. Create a project (or select an existing one)
3. Enable these APIs (APIs & Services > Enable APIs):
   • Google Docs API
   • Google Sheets API
   • Google Drive API
   • Google Calendar API
   • Gmail API
4. Configure OAuth consent screen:
   • User type: External
   • Add your email as a test user
5. Create credentials:
   • APIs & Services > Credentials > Create Credentials > OAuth 2.0 Client ID
   • Application type: Desktop app
   • Download the JSON file

2. Authenticate

# Save the client secret:
mkdir -p ~/.config/gdoc-mcp
cp ~/Downloads/client_secret_*.json ~/.config/gdoc-mcp/client_secret.json

# Run the OAuth flow (opens browser):
npm run auth

This opens your browser for Google OAuth consent, then saves tokens to ~/.config/gdoc-mcp/tokens.json.

SSH / headless environments: The auth URL is printed to the terminal. Visit it in any browser. If the localhost redirect fails, copy the URL from your browser's address bar and paste it back into the terminal.

Tokens auto-refresh. You only need to re-run npm run auth if you revoke access or the refresh token expires.

Troubleshooting: "API has not been used in project" or "is disabled"

If you see errors like:

Google Docs API has not been used in project 454715852682 before or it is disabled.

The required Google APIs have been disabled on the GCP project. Re-enable them with gcloud CLI:

gcloud services enable \
  docs.googleapis.com \
  drive.googleapis.com \
  sheets.googleapis.com \
  calendar-json.googleapis.com \
  gmail.googleapis.com \
  --project=panozzaj-general

Or enable them individually in the Google Cloud Console.

After re-enabling, the MCP server should work immediately (no restart needed). If you also had to re-run npm run auth, you'll need to restart the MCP server (e.g., /reload in Claude Code) so it picks up the new tokens.

Troubleshooting: "OAuth tokens have expired or been revoked"

cd ~/Documents/dev/gdoc-mcp
npm run auth    # Opens browser for OAuth consent

Then restart the MCP server (/reload in Claude Code) so it loads the new tokens from ~/.config/gdoc-mcp/tokens.json.

Configuration

Add to your Claude MCP config:

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

Tools

Google Docs

Google Sheets

Google Calendar

Anywhere a calendarId is accepted you can pass a calendar's display name (case-insensitive).

Gmail

Comparison with Other MCP Servers

Most Google Docs MCP servers have no concurrency protection, making them vulnerable to silent data loss when documents are edited concurrently.

How gdoc-mcp handles concurrency:

1. gdoc_read must be called first (caches revision, ensures you've seen the content)
2. gdoc_edit fetches current document state
3. Verifies old_text still exists in document
4. If found, edit proceeds; if not, error with message to re-read

This prevents silent overwrites while allowing concurrent edits to different parts of a document.

Limitations

• Edit scope: Text in paragraphs and table cells can be edited with inline formatting. Headings, lists, and images are readable but not directly editable.
• Complex formatting: Colors, fonts, and nested styles aren't preserved.
• Calendar: Recurring event management not yet supported.
• Gmail: Draft and read only — no send capability (by design, for safety). Plain text drafts only.

Development

npm run dev          # Watch mode (recompile on change)
npm test             # Run tests
npm run test:watch   # Watch mode tests
npm run build        # One-time build
npm run auth         # Re-run OAuth flow

License

MIT