Google Workspace MCP Server

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

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

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