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

Related MCP server: Google Drive MCP Server

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

Development

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