Google Workspace MCP Server

English | Simplified Chinese | Traditional Chinese

A comprehensive MCP (Model Context Protocol) server providing full Google Workspace integration - including Google Docs, Sheets, Drive, Gmail, Calendar, and Apps Script APIs. Compatible with Claude Code CLI, Cursor IDE, and other MCP-compatible clients.

Unique Feature: This is the only Google Workspace MCP server that supports Apps Script API - enabling AI-driven automation of Google Sheets, Docs, and other Workspace products.

Features

This server provides 72 tools across 6 Google Workspace services:

| Service | Tools | Description | |---------|-------|-------------| | Google Docs | 15 | Read, write, format, style, images, tables, comments | | Google Sheets | 14 | Read, write, format, create spreadsheets, manage sheets | | Google Drive | 16 | List, search, create, move, copy, delete files and folders | | Gmail | 15 | Search, read, send, drafts, labels, filters, threads | | Google Calendar | 8 | List calendars, events, create, update, delete, free/busy | | Apps Script | 4 | Create and manage bound scripts for automation |

Google Docs (15 tools)

• Document Operations: readGoogleDoc, appendToGoogleDoc, insertText, deleteRange, listDocumentTabs
• Formatting: applyTextStyle, applyParagraphStyle, formatMatchingText, fixListFormatting
• Structure: insertTable, editTableCell, insertPageBreak, findElement
• Images: insertImageFromUrl, insertLocalImage

Google Docs Comments (6 tools)

• Comment Management: listComments, getComment, addComment, replyToComment, resolveComment, deleteComment

Google Sheets (14 tools)

• Data Operations: readSpreadsheet, writeSpreadsheet, appendSpreadsheetRows, clearSpreadsheetRange
• Sheet Management: getSpreadsheetInfo, addSpreadsheetSheet, createSpreadsheet, listGoogleSheets
• Formatting: formatSpreadsheetCells, setBasicFilter, clearBasicFilter

Google Drive (16 tools)

• Discovery: listGoogleDocs, searchGoogleDocs, getRecentGoogleDocs, getDocumentInfo
• Folders: createFolder, listFolderContents, getFolderInfo
• File Operations: moveFile, copyFile, renameFile, deleteFile
• Creation: createDocument, createFromTemplate

Apps Script (4 tools)

• Script Management: createBoundScript, updateScriptContent, getScriptContent, getScriptProjects

Gmail (15 tools)

• Messages: searchGmailMessages, getGmailMessage, getGmailMessagesBatch, getGmailAttachment
• Send & Draft: sendGmailMessage, createGmailDraft
• Threads: getGmailThread
• Labels: listGmailLabels, createGmailLabel, deleteGmailLabel, modifyGmailMessageLabels
• Filters: listGmailFilters, createGmailFilter, deleteGmailFilter
• Management: trashGmailMessage

Google Calendar (8 tools)

• Calendars: listCalendars
• Events: getCalendarEvents, getCalendarEvent, createCalendarEvent, updateCalendarEvent, deleteCalendarEvent
• Quick Actions: quickAddCalendarEvent
• Availability: getCalendarFreeBusy

Prerequisites

• Node.js v18+ with npm
• Git for cloning the repository
• Google Account with access to Google Workspace
• MCP-compatible client: Claude Code CLI, Cursor IDE, or other MCP clients

Quick Start

Option A: Interactive Setup Wizard (Recommended)

git clone https://github.com/sputnicyoji/google-docs-mcp-for-claudecode.git
cd google-docs-mcp-for-claudecode
npm install
npm run setup

The setup wizard will:

• Check your environment (Node.js, npm, build)
• Auto-build TypeScript if needed
• Guide you through credential setup
• Run OAuth authorization
• Generate and optionally auto-update Claude Code CLI config

Option B: Manual Setup

1. Clone and Install

git clone https://github.com/sputnicyoji/google-docs-mcp-for-claudecode.git
cd google-docs-mcp-for-claudecode
npm install
npm run build

2. Google Cloud Setup

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the following APIs:
   • Google Docs API
   • Google Sheets API
   • Google Drive API
   • Apps Script API
   • Gmail API
   • Google Calendar API
4. Configure OAuth consent screen:
   • Select "External" user type
   • Add required scopes: documents, spreadsheets, drive.file, script.projects, gmail, calendar
   • Add your email as a test user
5. Create OAuth credentials:
   • Go to Credentials > Create Credentials > OAuth client ID
   • Select "Desktop app"
   • Download the JSON file and save as credentials.json in the project root

3. Authenticate

node ./dist/server.js

Follow the URL in the terminal to authorize access. After authorization, a token.json will be created.

4. Configure Claude Code CLI

Add to your Claude Code MCP configuration:

Windows (%APPDATA%\Claude\mcp_config.json):

{
  "mcpServers": {
    "google-workspace": {
      "command": "node",
      "args": ["C:\\path\\to\\google-docs-mcp-for-claudecode\\dist\\server.js"]
    }
  }
}

macOS/Linux (~/.config/Claude/mcp_config.json):

{
  "mcpServers": {
    "google-workspace": {
      "command": "node",
      "args": ["/path/to/google-docs-mcp-for-claudecode/dist/server.js"]
    }
  }
}

5. Configure Cursor IDE (Alternative)

This MCP server is fully compatible with Cursor IDE.

Project-Level Configuration - Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "google-workspace": {
      "command": "node",
      "args": ["/path/to/google-docs-mcp-for-claudecode/dist/server.js"]
    }
  }
}

Global Configuration - Or configure via Cursor Settings > MCP.

Note: Cursor must be in Agent Mode (not Ask Mode) to access MCP tools.

Service Account Authentication (Alternative)

For automated/server environments, you can use a service account:

1. Create a service account in Google Cloud Console
2. Download the JSON key file
3. Set environment variable:

   export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json
   

4. Share your Google Docs/Sheets with the service account email

Usage Examples

Google Docs

Read document 1abc...xyz and return as markdown
Append "Meeting Notes" to document 1abc...xyz
Apply bold formatting to text "Important" in document 1abc...xyz
Insert a 3x4 table at index 100 in document 1abc...xyz

Google Sheets

Read range A1:D10 from spreadsheet 1abc...xyz
Write data to range A1:B5 in spreadsheet 1abc...xyz
Create a new spreadsheet titled "Sales Report 2024"
Add a new sheet named "Summary" to spreadsheet 1abc...xyz

Google Drive

List all Google Docs in my Drive
Search for documents containing "Project Alpha"
Create a new folder named "2024 Reports"
Move file 1abc...xyz to folder 2def...uvw

Apps Script

Create a bound script for spreadsheet 1abc...xyz
Update script content with custom functions
Get content of script project 1abc...xyz

Gmail

Search for unread emails from john@example.com
Read email message with ID abc123
Send an email to jane@example.com with subject "Meeting"
Create a draft reply to thread xyz789
List all Gmail labels
Create a filter to label emails from support@example.com

Google Calendar

List all my calendars
Get events for this week from my primary calendar
Create a meeting titled "Team Standup" tomorrow at 10am
Quick add event "Lunch with Sarah on Friday at noon"
Check free/busy times for next Monday
Delete event abc123 from my calendar

Project Structure

google-docs-mcp-for-claudecode/
  src/
    server.ts              # Main MCP server (tool definitions)
    clients.ts             # Google API client management
    auth.ts                # OAuth 2.0 / Service Account authentication
    types.ts               # TypeScript type definitions
    helpers/
      markdown.ts          # Docs to Markdown conversion
      index.ts             # Helper re-exports
    tools/
      scriptTools.ts       # Apps Script tools
      gmailTools.ts        # Gmail tools
      calendarTools.ts     # Calendar tools
      index.ts             # Tool registry
    googleDocsApiHelpers.ts    # Docs API helpers
    googleSheetsApiHelpers.ts  # Sheets API helpers
    gmailApiHelpers.ts         # Gmail API helpers
    calendarApiHelpers.ts      # Calendar API helpers
  dist/                    # Compiled JavaScript
  credentials.json         # OAuth credentials (not committed)
  token.json               # Auth token (not committed)

Security Notes

• Never commit credentials.json or token.json to version control
• The .gitignore file is configured to exclude sensitive files
• For production, consider using secret management services
• Service account keys should be stored securely

Known Limitations

• Comment Anchoring: Programmatically created comments may show "original content deleted" instead of anchoring to specific text
• Converted Documents: Some documents converted from other formats (e.g., Word) may not support all API operations
• Quota Limits: Google APIs have usage quotas - check Google Cloud Console for limits

Troubleshooting

Connection Issues

1. Verify the path in mcp_config.json is absolute and correct
2. Ensure npm run build completed successfully
3. Test manually: node ./dist/server.js

Authentication Errors

1. Verify all required APIs are enabled
2. Check that your email is added as a test user
3. Delete token.json and re-authenticate if scopes changed

Tab/Sheet Errors

1. Use listDocumentTabs or getSpreadsheetInfo to verify IDs
2. Ensure you're using correct ID formats

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Submit a pull request

Credits

Based on a-bonus/google-docs-mcp with additional enhancements:

• Google Apps Script API integration
• Gmail and Google Calendar API integration
• Service Account authentication support
• Modular code architecture
• Multi-language documentation

License

MIT License - see LICENSE for details.