Google Workspace MCP Server

A read-only MCP server that provides access to Google Workspace APIs — Gmail, Drive, Sheets, Docs, Slides, Calendar, and Admin Directory. It uses a GCP service account with domain-wide delegation to impersonate workspace users.

Prerequisites

• Node.js 18+
• A Google Cloud project with a service account that has domain-wide delegation enabled
• The service account's JSON key file downloaded locally

Required API Scopes

When configuring domain-wide delegation in your Google Workspace Admin Console, grant the service account these scopes:

https://www.googleapis.com/auth/gmail.readonly
https://www.googleapis.com/auth/drive.readonly
https://www.googleapis.com/auth/admin.directory.user.readonly
https://www.googleapis.com/auth/spreadsheets.readonly
https://www.googleapis.com/auth/documents.readonly
https://www.googleapis.com/auth/calendar.readonly
https://www.googleapis.com/auth/presentations.readonly

Google Cloud Setup

1. Create a GCP Project

1. Go to the Google Cloud Console
2. Click Select a project > New Project
3. Name it (e.g., workspace-mcp-server) and click Create
4. Select the newly created project

2. Enable APIs

Enable the following APIs in APIs & Services > Library (or click the links below):

• Gmail API
• Google Drive API
• Google Sheets API
• Google Docs API
• Admin SDK API
• Google Calendar API
• Google Slides API

For each one, click Enable.

3. Create a Service Account

1. Go to IAM & Admin > Service Accounts
2. Click Create Service Account
3. Give it a name (e.g., workspace-mcp) and click Create and Continue
4. Skip the optional "Grant this service account access" and "Grant users access" steps — click Done
5. Click on the newly created service account
6. Go to the Keys tab
7. Click Add Key > Create new key > JSON and click Create
8. Save the downloaded JSON key file somewhere secure (e.g., ~/.config/gcp/service-account-key.json)

Warning: This key file grants access to your Workspace data. Never commit it to version control.

4. Enable Domain-Wide Delegation

1. On the service account details page, click Show Advanced Settings
2. Under Domain-wide delegation, click Enable Google Workspace Domain-wide Delegation
3. Note the Client ID (a numeric string) — you'll need it in the next step

5. Grant Scopes in Google Workspace Admin

1. Go to the Google Workspace Admin Console

2. Navigate to Security > Access and data control > API controls

3. Click Manage Domain Wide Delegation

4. Click Add new

5. Enter the Client ID from step 4

6. In the OAuth scopes field, paste all seven scopes (comma-separated):

   https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/drive.readonly,https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/spreadsheets.readonly,https://www.googleapis.com/auth/documents.readonly,https://www.googleapis.com/auth/calendar.readonly,https://www.googleapis.com/auth/presentations.readonly
   

7. Click Authorize

Note: The admin.directory.user.readonly scope requires the impersonated user to be a Workspace admin. The other scopes work for any user in the domain.

Installation

git clone git@github.com:obe711/google-workspace-mcp.git
cd google-workspace-mcp
npm install
npm run build

Configuration

1. Copy the example environment file:

   cp .env.example .env
   

2. Edit .env and set:

   • GOOGLE_SERVICE_ACCOUNT_KEY_PATH — Absolute path to your service account JSON key file
   • GW_USER_EMAIL — The default Google Workspace email to impersonate when userEmail is not passed to a tool (e.g., you@yourdomain.com)

   GOOGLE_SERVICE_ACCOUNT_KEY_PATH=/Users/me/keys/service-account-key.json
   GW_USER_EMAIL=you@yourdomain.com
   

Note: .env is git-ignored and will not be committed. Never commit your service account key file.

Usage with Claude Code

1. Register the MCP server

Add the server to your Claude Code MCP config (project-level .mcp.json or global ~/.claude/mcp.json):

{
  "mcpServers": {
    "google-workspace": {
      "command": "node",
      "args": ["build/index.js"],
      "cwd": "/absolute/path/to/google-workspace-mcp"
    }
  }
}

The server reads all configuration from the .env file — no env overrides are needed in the MCP config.

2. Use the /gw skill

Once configured, use the /gw slash command in Claude Code:

/gw search my recent emails about project updates
/gw find spreadsheets modified this week
/gw read the Q4 budget document
/gw list workspace users

Available Tools

Tool	Description
search_emails	Search Gmail using Gmail query syntax
get_email	Get full content of an email by message ID
list_labels	List all Gmail labels
search_drive_files	Search Google Drive files
get_file_content	Read the content of a Drive file
get_file_metadata	Get metadata for a Drive file
get_spreadsheet	Get spreadsheet metadata (sheets, dimensions)
read_sheet_range	Read cell values from a spreadsheet range
batch_read_sheet_ranges	Read multiple spreadsheet ranges at once
get_document	Get full text content of a Google Doc
get_document_structure	Get heading outline of a Google Doc
list_users	List Google Workspace users (requires admin)
list_calendars	List all calendars a user has access to
search_events	Search/list calendar events in a date range
get_event	Get full details of a calendar event
get_freebusy	Query free/busy status for one or more users
search_presentations	Search for Google Slides presentations
get_presentation	Get presentation metadata and slide overview
get_slide	Get full text content of a single slide

Development

npm run dev    # Watch mode — recompiles on changes
npm run build  # One-time build
npm start      # Run the server