Claude MCP x Google Docs

Google Docs, Sheets & Drive MCP Server

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

---

Quick Start

1. Create a Google Cloud OAuth Client

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.

2. Authorize

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.

3. Add to Your MCP Client

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.

---

What Can It Do?

Google Docs

Comments

Google Sheets

Google Sheets Tables

Table Usage Examples:

"Create a table named 'Project Tracker' in range A1:E10 with a Status dropdown column"
"List all tables in spreadsheet XYZ789"
"Get details for table 'Project Tracker'"
"Append 3 rows to table 'Project Tracker'"
"Delete table 'Project Tracker' but keep the data"

Google Drive

---

Usage Examples

Google Docs

"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"

Google Sheets

"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)"

Google Drive

"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"

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.

---

Authentication Options

OAuth (Default)

Pass your Google Cloud OAuth client credentials as environment variables:

Service Account (Enterprise)

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"
      }
    }
  }
}

Token Storage

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.

Multiple Google Accounts

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.

---

Known Limitations

• 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.

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, 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 listDocumentTabs to see available tab IDs.
  • Omit tabId for single-tab documents.

---

Google Cloud Setup Details

Step-by-step Google Cloud Console instructions

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
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
   • 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

---

Contributing

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

License

MIT -- see LICENSE for details.