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

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

$3

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

$3

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

$3

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

$3

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!

$3

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!

$3

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

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

$3

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

Tools

$3

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

$3

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

$3

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

$3

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

$3

| 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

$3

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.

$3

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

$3

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

`bash


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