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 [email protected]"
• "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