google-workspace-mcp

A multi-account Google Workspace MCP server for Claude Code. Drives Gmail, Google Calendar, and Google Drive across any number of Google accounts in parallel from one server — every tool takes an account slug, so a single Claude session can email from one account, file in another's Drive, and book an event in a third.

You bring your own Google Cloud OAuth client, so you own the access and get the full tool surface — including things the default claude.ai connector can't do, like deleting a draft.

Ships as a Claude Code plugin (this repo is also its own marketplace).

How it works

• One server, many accounts. Each tool call passes an account slug (e.g. work, personal). The server loads and refreshes that account's OAuth token transparently.

• You decide which accounts a project can touch. Accounts are not baked into the code — they're configured at runtime (see Define your accounts). A per-project .mcp.json can scope a project to a specific subset, so e.g. a personal project never even sees your work account.

• Secrets live outside the repo. Your OAuth client and per-account tokens are stored under ~/.config/google-workspace-mcp/, never in the code tree.

Requires uv on your PATH.

Related MCP server: Google-Workspace-MCP-Server

Setup

1. Install the plugin

/plugin marketplace add rajool/google-workspace-mcp
/plugin install google-workspace-mcp@google-workspace-mcp

This gives you the /google-workspace-setup command, which can walk you through the rest. The manual steps follow.

2. Create your own Google Cloud OAuth client

Each user creates their own client (free):

1. Go to the Google Cloud Console and create a project (or pick one).

2. APIs & Services → Enabled APIs & Services → + Enable APIs — enable Gmail API, Google Calendar API, and Google Drive API.

3. APIs & Services → OAuth consent screen — User type External. Fill the required fields. Under Test users, add every Google account you intend to connect. (Leaving the app in Testing is fine.)

4. APIs & Services → Credentials → + Create credentials → OAuth client ID → Application type: Desktop app. Download the JSON.

5. Save that JSON as:

   ~/.config/google-workspace-mcp/credentials.json

3. Install the server binary

So a project's .mcp.json can launch it by name:

# from GitHub:
uv tool install git+https://github.com/rajool/google-workspace-mcp

# …or from a local clone:
uv tool install .

This installs two commands: google-workspace-mcp (the server) and google-workspace-authorize (the OAuth helper).

4. Define your accounts

Give each account a short slug. Two ways:

a) A registry file (recommended) — ~/.config/google-workspace-mcp/accounts.json:

{
  "accounts": {
    "work":     { "email": "you@company.com",  "name": "Your Name" },
    "personal": { "email": "you@gmail.com",     "name": "Your Name" }
  }
}

name is the display name shown in the From: header on sent mail (set it to "" to send with the bare address).

b) Or inline per project via the GWM_ACCOUNTS env var (see below) — handy if you don't want a shared registry file.

5. Authorize each account

This opens a Google consent URL — open it in a browser signed into that account and click Allow:

# account already in accounts.json — just the slug:
google-workspace-authorize work

# or register a brand-new account inline (adds it to accounts.json):
google-workspace-authorize personal you@gmail.com "Your Name"

You'll click through the "Google hasn't verified this app" warning (it's your own app) → Continue → Select all → Continue. The refresh token is written to ~/.config/google-workspace-mcp/tokens/<slug>.json.

6. Wire it into a project

Add a .mcp.json at the project root. GWM_ACCOUNTS decides which accounts this project may use.

{
  "mcpServers": {
    "google-workspace": {
      "command": "google-workspace-mcp",
      "env": { "GWM_ACCOUNTS": "work,personal" }
    }
  }
}

• GWM_ACCOUNTS can be a comma-list of slugs from your registry (above), or an inline JSON map ({"work":{"email":"…","name":"…"}}) if you skipped the registry.

• Omit GWM_ACCOUNTS to expose every account in the registry.

Restart Claude Code (or reconnect MCP) to pick it up, then ask Claude to list accounts to confirm.

Per-project access control

The point of GWM_ACCOUNTS is isolation: a project literally cannot act as an account that isn't in its list — the server refuses the slug. Tokens are stored centrally (authorize once), but each project's .mcp.json chooses its own slice. Example:

Tool surface

Every call requires an account slug.

• accounts_list — configured accounts + which have valid tokens

• Gmail — gmail_send, gmail_draft_create, gmail_draft_update, gmail_draft_send, gmail_draft_delete, gmail_drafts_list, gmail_search, gmail_thread_get, gmail_message_get, gmail_message_modify, gmail_message_trash, gmail_labels_list

• Calendar — calendar_list, calendar_events_list, calendar_event_get, calendar_event_create, calendar_event_update, calendar_event_delete

• Drive — drive_search, drive_file_get, drive_file_download, drive_file_upload, drive_file_move, drive_file_rename, drive_file_trash, drive_file_share, drive_folder_create

• Tasks — tasklist_list, tasklist_create, tasklist_delete, task_list, task_get, task_create, task_update, task_complete, task_delete, task_move

Configuration & storage

Everything lives under the config home — $GWM_HOME, else $XDG_CONFIG_HOME/google-workspace-mcp, else ~/.config/google-workspace-mcp/:

Token files are written 0600.

Scopes

Broad on purpose — these are your own accounts; narrower scopes would force a re-auth every time a tool is added.

• https://mail.google.com/

• https://www.googleapis.com/auth/calendar

• https://www.googleapis.com/auth/drive

• https://www.googleapis.com/auth/tasks

Security notes

• The OAuth client and tokens are yours and stay on your machine, outside this repo. Never commit credentials.json or tokens/.

• Each teammate runs their own OAuth client and authorizes their own accounts — nothing is shared between users.

• Tokens grant broad access to your mail/calendar/drive; treat ~/.config/google-workspace-mcp/ like any other secret store.

License

MIT © Ali Rajool. See LICENSE.