Google Workspace MCP Server

MCP server for Google Workspace APIs - Docs, Sheets, Drive, Gmail, and Calendar. Use it with Claude Code to read, create, and edit Google Docs and Sheets, manage comments, read emails, and view calendar events.

Quick Start

1. Get your Google credentials (see Setup below)
2. Add to your Claude Code config (~/.claude.json):

{
  "mcpServers": {
    "google-workspace": {
      "type": "stdio",
      "command": "npx",
      "args": ["google-workspace-mcp-server"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret",
        "GOOGLE_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

3. Restart Claude Code

Setup

Step 1: Create a Google Cloud Project

1. Go to Google Cloud Console
2. Click the project dropdown (top left) → New Project
3. Name it something like "MCP Server" → Create
4. Wait for the project to be created, then select it

Step 2: Enable the APIs

1. Go to APIs & Services → Library (or click here)
2. Search for and enable each of these APIs:
   • Google Docs API → Click → Enable
   • Google Sheets API → Click → Enable
   • Google Drive API → Click → Enable
   • Gmail API → Click → Enable
   • Google Calendar API → Click → Enable

Step 3: Configure OAuth Consent Screen

1. Go to APIs & Services → OAuth consent screen
2. Select user type:
   • Internal (only if you have Google Workspace) - simpler, no test user setup needed
   • External (for personal Gmail accounts) - requires adding yourself as a test user
3. Click Create
4. Fill in the required fields:
   • App name: "MCP Server" (or anything)
   • User support email: your email
   • Developer contact email: your email
5. Click Save and Continue
6. On Scopes page, click Save and Continue (no changes needed)
7. On Test users page (External only): click Add Users → add your Google email → Save and Continue
8. Click Back to Dashboard

Step 4: Create OAuth Credentials

1. Go to APIs & Services → Credentials
2. Click Create Credentials → OAuth client ID
3. Application type: Web application
4. Name: "MCP Server" (or anything)
5. Under Authorized redirect URIs, click Add URI and enter:

   https://developers.google.com/oauthplayground
   

6. Click Create
7. Copy and save your Client ID and Client Secret - you'll need these!

Step 5: Get Your Refresh Token

1. Go to OAuth 2.0 Playground

2. Click the gear icon (⚙️) in the top right corner

3. Check "Use your own OAuth credentials"

4. Enter your Client ID and Client Secret from Step 4

5. Close the settings

6. In the left panel, find and select these scopes:

   • Google Docs API v1 → https://www.googleapis.com/auth/documents
   • Google Sheets API v4 → https://www.googleapis.com/auth/spreadsheets
   • Google Drive API v3 → https://www.googleapis.com/auth/drive
   • Gmail API v1 → https://www.googleapis.com/auth/gmail.readonly
   • Gmail API v1 → https://www.googleapis.com/auth/gmail.compose (for creating drafts)
   • Google Calendar API v3 → https://www.googleapis.com/auth/calendar.readonly

7. Click Authorize APIs

8. Sign in with your Google account and grant permissions

   • If you see "Google hasn't verified this app", click Advanced → Go to MCP Server (unsafe)
   • Click Continue to grant permissions

9. Click Exchange authorization code for tokens

10. Copy the Refresh Token (not the Access Token!) - this is what you need!

Step 6: Configure Claude Code

Add the MCP server to your Claude Code settings. Edit ~/.claude.json:

{
  "mcpServers": {
    "google-workspace": {
      "type": "stdio",
      "command": "npx",
      "args": ["google-workspace-mcp-server"],
      "env": {
        "GOOGLE_CLIENT_ID": "123456789-abcdefg.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "GOCSPX-xxxxxxxxxxxxx",
        "GOOGLE_REFRESH_TOKEN": "1//04xxxxxxxxxxxxx"
      }
    }
  }
}

Replace the values with your actual credentials from Steps 4 and 5.

Step 7: Restart Claude Code

Restart Claude Code to load the new MCP server. You should now be able to use Google Workspace tools!

Tools

Google Docs API

Tool	Description
docs_get_document	Get document content by ID
docs_create_document	Create a new document
docs_batch_update	Insert/update/delete text, formatting, images, tables

Google Sheets API

Tool	Description
sheets_get_spreadsheet	Get spreadsheet metadata
sheets_get_values	Read cell values from a range
sheets_batch_get_values	Read from multiple ranges
sheets_update_values	Write values to a range
sheets_append_values	Append rows to a table
sheets_create_spreadsheet	Create a new spreadsheet
sheets_batch_update	Apply formatting, charts, filters
sheets_clear_values	Clear cell values from a range
sheets_duplicate_sheet	Duplicate a sheet within a spreadsheet

Google Drive API

Tool	Description
drive_get_file	Download file content (PDFs, images, etc.)
drive_list_files	List files in your Drive
drive_search_files	Search for files by name or content
drive_copy_file	Create a copy of a file
drive_list_comments	List comments on a document
drive_create_comment	Add a comment (anchored or unanchored)
drive_reply_to_comment	Reply to an existing comment
drive_resolve_comment	Mark comment as resolved
drive_delete_comment	Delete a comment

Gmail API

Tool	Description
gmail_list_messages	List messages with optional search filters
gmail_get_message	Get full content of a specific message
gmail_list_threads	List conversation threads
gmail_get_thread	Get all messages in a thread
gmail_list_labels	List all Gmail labels (folders)
gmail_create_draft	Create an email draft (not sent automatically)
gmail_list_attachments	List attachments in a message
gmail_get_attachment	Download an attachment

Google Calendar API (Read-Only)

Tool	Description
calendar_list_calendars	List all accessible calendars
calendar_list_events	List events with time range and search filters
calendar_get_event	Get detailed event information
calendar_freebusy_query	Check free/busy availability for calendars

Usage Examples

Once configured, you can ask Claude Code things like:

• "Read my Google Doc at https://docs.google.com/document/d/abc123/edit"
• "Read this PDF from my Drive: https://drive.google.com/file/d/xyz789/view"
• "Create a new Google Doc with meeting notes from today"
• "Add a row to my spreadsheet with today's data"
• "Search my Drive for files about project planning"
• "Show me the comments on this document"
• "Reply to John's comment saying I'll fix it tomorrow"
• "Show me my unread emails"
• "Find emails from notifications@github.com"
• "What's on my calendar today?"
• "Show me my meetings for this week"
• "Get the details of that standup meeting"

Troubleshooting

"Access token expired" errors

The MCP server automatically refreshes tokens using your refresh token. If you see this error, your refresh token may have been revoked. Go through Step 5 again to get a new one.

"App not verified" warning

This is normal for personal projects. Click Advanced → Go to [App Name] (unsafe) to proceed.

"Insufficient permissions" errors

Make sure you enabled all five APIs (Docs, Sheets, Drive, Gmail, Calendar) in Step 2, and selected all five scopes in Step 5.

Environment Variables

Variable	Description
GOOGLE_CLIENT_ID	OAuth 2.0 Client ID from Google Cloud Console
GOOGLE_CLIENT_SECRET	OAuth 2.0 Client Secret
GOOGLE_REFRESH_TOKEN	Refresh token from OAuth Playground

Development

# Clone the repo
git clone https://github.com/nityeshaga/google-workspace-mcp-server.git
cd google-workspace-mcp-server

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm start

License

MIT