gws-mcp: Google Workspace MCP server (multi-account)

A local MCP server that gives Claude Desktop access to Gmail, Google Calendar and Google Drive on one or more Google Workspace accounts. Each account gets an alias (e.g. work) and every tool takes an optional account argument.

• Read-only by default. Write access is opt-in per account.

• No sending, no deleting. Even with write enabled, there are no tools to send email, send drafts, delete, trash or cancel anything. You send your own emails.

• Tokens in the macOS Keychain (or an encrypted file on servers), never in plain text.

• Nothing sensitive is logged. Logs go to stderr and token-shaped strings are redacted.

Contents

1. Tools

2. Security model

3. Google Cloud setup (one time per Workspace organization)

4. Install

5. Add an account

6. Add to Claude Desktop

7. Turn write access on or off

8. More accounts

9. Token storage options

10. Troubleshooting

11. Development

Related MCP server: Mariana Google MCP

Tools

Notes:

• drive_read_file exports Google Docs and Slides as plain text and Sheets as CSV (first sheet only). Other files (PDF, images, Office files) are saved to the downloads folder.

• Attachments and Drive files are saved to ~/Downloads/gws-mcp by default. Existing files are never overwritten; a numbered copy is created instead.

• Reply drafts are attached to the original conversation (threadId, In-Reply-To, References, Re: subject).

Security model

Two layers protect write access. A write tool only works when both are true for the account:

1. write = true is set for the account in the config file, and

2. Google actually granted the write permissions (scopes) to the stored token.

If no account has write = true, write tools are not registered at all and Claude does not see them. If one account has write on and another off, the tools are visible but refuse to act on the read-only account.

Scopes requested from Google:

Google has no "drafts only" scope: gmail.modify would technically allow sending and trashing, and calendar.events would allow deleting. This server blocks those actions in its own code. The tools simply do not exist, adding the TRASH/SPAM labels is refused, and event status (cancellation) cannot be changed. drive.file lets the server write only files it created itself, so your existing Drive files can never be changed.

Drafts. Drafts created by Claude carry a hidden X-GWS-MCP header. gmail_update_draft only changes those. To change a draft you wrote, Claude must use gmail_update_user_draft, which requires the draft's exact current subject and refuses drafts with attachments. Set that tool to "Always ask" in Claude Desktop (see below) so you approve every change.

Calendar. Creating or updating events never sends invitation or update emails (sendUpdates = none).

Untrusted content. Emails, events and files can contain text that tries to instruct an AI. The server tells Claude to treat such content as data only. Keep write access off unless you need it.

Google Cloud setup

Do this once for each Google Workspace organization (you need to be its admin, or have permission to create Cloud projects). Google renames console menus from time to time; the names below match the console as of 2026.

1. Create a project

1. Open https://console.cloud.google.com/ and sign in with an account in the Workspace organization you want to connect.

2. Click the project picker at the top, then New project.

3. Name it e.g. gws-mcp. Make sure Organization is your Workspace organization, then click Create and select the new project.

2. Enable the APIs

1. Go to APIs & Services → Library.

2. Search for and Enable each of these:

   • Gmail API

   • Google Calendar API

   • Google Drive API

3. Configure the consent screen (Internal)

1. Go to APIs & Services → OAuth consent screen (shown as Google Auth Platform). Click Get started if prompted.

2. App information: app name gws-mcp, user support email = your address. Click Next.

3. Audience: choose Internal. This limits the app to users in your organization, needs no Google verification, and keeps refresh tokens from expiring after 7 days. (If Internal is greyed out, the project is not inside a Workspace organization; go back to step 1.)

4. Contact information: your email. Agree to the policy and click Create.

5. Optional: under Data access, click Add or remove scopes and add the scopes from the Security model table. The server requests them itself, so this step only documents them.

4. Create a Desktop OAuth client

1. Go to Clients (or APIs & Services → Credentials → Create credentials → OAuth client ID).

2. Application type: Desktop app. Name: gws-mcp desktop. Click Create.

3. Click Download JSON. Keep this file private: it identifies your app.

Repeat steps 1-4 in each additional Workspace organization. An Internal app only works for accounts in its own organization.

Install

Requirements: macOS (Windows and Linux also work) and uv. uv downloads Python 3.12 for this project automatically; your system Python is not changed.

cd ~/google-workspace-mcp
uv sync            # creates .venv and uv.lock, installs dependencies
uv run gws-mcp --version

Add an account

1. Create the config folder and put the client JSON in it:

   mkdir -p ~/.config/gws-mcp/clients
   mv ~/Downloads/client_secret_*.json ~/.config/gws-mcp/clients/your-company.json
   chmod 600 ~/.config/gws-mcp/clients/your-company.json
   cp ~/google-workspace-mcp/config.example.toml ~/.config/gws-mcp/config.toml

2. Edit ~/.config/gws-mcp/config.toml:

   default_account = "work"
   
   [accounts.work]
   email = "you@your-company.com"
   client_secrets = "~/.config/gws-mcp/clients/your-company.json"
   write = false

   Aliases are 1-32 characters: lowercase letters, digits, - and _.

3. Authorize it. A browser window opens; sign in with that account and click Allow:

   uv run gws-mcp auth work

   The token is saved only if the account you signed in with matches email. On macOS you may be asked to allow access to the Keychain: choose Always Allow.

4. Check it:

   uv run gws-mcp accounts
   # * work   you@your-company.com   write=off  authorized

Add to Claude Desktop

1. Find the full path of uv (Claude Desktop does not use your shell's PATH):

   which uv        # e.g. /opt/homebrew/bin/uv

2. In Claude Desktop open Settings → Developer → Edit Config. This opens ~/Library/Application Support/Claude/claude_desktop_config.json. Add the server under mcpServers (keep any servers already there):

   {
     "mcpServers": {
       "google-workspace": {
         "command": "/opt/homebrew/bin/uv",
         "args": [
           "--directory", "/Users/YOUR_USER/google-workspace-mcp",
           "run", "gws-mcp", "serve"
         ]
       }
     }
   }

   To use a config file elsewhere, add "env": {"GWS_MCP_CONFIG": "/path/to/config.toml"}.

3. Quit Claude Desktop completely (Cmd+Q) and open it again. The tools appear under the tools/connectors menu in the chat box.

4. Recommended: in the tool permissions, set gmail_update_user_draft (and any other write tool you want to approve one by one) to Always ask.

Turn write access on or off

Turn on:

1. Set write = true for the account in config.toml.

2. Re-authorize so Google grants the extra permissions:

   uv run gws-mcp auth work

3. Restart Claude Desktop.

Until step 2 is done, write tools refuse with a message telling you to re-authorize.

Turn off:

1. Set write = false and restart Claude Desktop. Write tools disappear (if no other account has write on) and are refused for this account in any case.

2. Optional, to also drop the permissions at Google: run uv run gws-mcp auth work again (read-only scopes only), and/or remove the app's access at https://myaccount.google.com/connections.

More accounts

Add another [accounts.<alias>] block and run uv run gws-mcp auth <alias>. Accounts from a different Workspace organization need their own Cloud project and client JSON (see Google Cloud setup).

With several accounts, set default_account or tell Claude which account to use (e.g. "search my home account"). Claude can call list_accounts to see the aliases.

Token storage options

uv run gws-mcp gen-key            # prints a key; store it like a password
export GWS_MCP_TOKEN_KEY="<key>"

[storage]
backend = "encrypted_file"
encrypted_file_path = "~/.config/gws-mcp/tokens.enc"

The file is Fernet-encrypted (AES-128 + HMAC) and written with 0600 permissions. Without the key it cannot be read.

Access tokens are refreshed automatically with the refresh token and the new token is saved. If a refresh token is revoked (password change, access removed, admin policy), tools return "Authorize it with: gws-mcp auth ".

Troubleshooting

Run with more logging: add "--log-level", "DEBUG" before "serve" in the Claude Desktop args. Logs never contain tokens or message content.

Development

uv sync
uv run pytest            # all Google API calls are mocked; no credentials needed
uv run ruff check . && uv run ruff format --check .

Layout:

src/gws_mcp/
  __main__.py        CLI: serve | auth <alias> | accounts | gen-key
  config.py          TOML config and account resolution
  scopes.py          read/write scope sets and the scope check
  logging_setup.py   stderr logging with redaction
  auth/              OAuth loopback flow, token storage, refresh
  google_clients.py  per-account API clients
  services/          Google API logic (no MCP dependency)
  tools/             MCP tool wrappers and the write guard
  server.py          builds the transport-agnostic MCP server
  entrypoints/       stdio runner (an HTTP + OAuth runner can be added here)

Moving to a server later only needs a new file in entrypoints/ (Streamable HTTP with MCP OAuth) plus backend = "encrypted_file"; tools and services stay unchanged.