google-workspace-mcp

Minimal, dependency-free MCP server for Gmail, Google Calendar and Google Drive, backed by Google's gws CLI. Works with a normal @gmail.com account.

Why not Google's official MCP servers? Google's hosted Workspace MCP endpoints (gmailmcp.googleapis.com, calendarmcp.googleapis.com, drivemcp.googleapis.com) are gated behind the Workspace Developer Preview Program, which requires a Google Workspace account and an application review. This server sidesteps that by calling the public Workspace APIs through gws with your own OAuth client.

Features

• Calendar: list calendars, upcoming agenda, create and delete events.

• Gmail: search with Gmail query syntax, read full messages (plain text, HTML stripped), send mail or save drafts.

• Drive: search files and upload files — uploads are pinned to one folder.

• Multiple accounts, each with its own credentials and an enforced capability list (e.g. send from one account, read another's calendar only).

• No npm dependencies, a single file, runs locally, no telemetry.

• Tool names are prefixed by your MCP client. Register the server as google to get google_calendar_list, google_gmail_search, etc. (OpenCode does this automatically.)

Related MCP server: Gmail Local MCP

Tools

Every tool accepts an optional account (default: the registry default); gmail_send requires it. See Multiple accounts.

There is intentionally no Gmail delete/label tool and no Drive delete/move/share tool. Sending is a deliberate, separate write tool (gmail_send); use draft: true when you want review before sending.

Requirements

• Node.js 18+

• gws on PATH (or set GWS_BIN)

• A Google Cloud project with a Desktop OAuth client

Setup

1. Install gws

brew install googleworkspace-cli
# or:
npm install -g @googleworkspace/cli

2. Google Cloud project

1. Create (or reuse) a project in Google Cloud Console.

2. Enable Gmail API, Google Calendar API and Google Drive API.

3. Configure the OAuth consent screen (Google Auth Platform → Branding): user type External, and add your own address under Test users.

4. Create an OAuth client of type Desktop app and save its JSON as:

~/.config/gws/client_secret.json

3. Authorize with least-privilege scopes

gws auth login \
  --scopes "https://www.googleapis.com/auth/gmail.modify,https://www.googleapis.com/auth/calendar,https://www.googleapis.com/auth/drive.readonly,https://www.googleapis.com/auth/drive.file"

gws auth export --unmasked > ~/.config/gws/credentials-export.json
chmod 600 ~/.config/gws/credentials-export.json

• drive.readonly + drive.file = read all of Drive, write only files this app creates.

• gmail.modify covers search/read/labels/drafts and sending.

• While the OAuth app is in Testing, Google expires refresh tokens after 7 days. Publish the app (Audience → Publish app) for long-lived tokens; an unverified app is fine for personal use.

4. Register the MCP server

OpenCode (~/.config/opencode/opencode.json):

{
  "mcp": {
    "servers": {
      "google": {
        "type": "local",
        "command": ["node", "/absolute/path/to/gws-mcp.cjs"],
        "environment": {
          "GWS_BIN": "/opt/homebrew/bin/gws"
        }
      }
    }
  }
}

With the server registered as google, OpenCode exposes the tools as google_calendar_list, google_gmail_search, and so on.

No clone needed — run it straight from this repository:

{
  "mcp": {
    "servers": {
      "google": {
        "type": "local",
        "command": ["npx", "-y", "github:Martins6/google-workspace-mcp"]
      }
    }
  }
}

(npx downloads the repo into its cache and runs the package's bin.)

Claude Desktop / other clients (mcpServers shape):

{
  "mcpServers": {
    "google": {
      "command": "node",
      "args": ["/absolute/path/to/gws-mcp.cjs"]
    }
  }
}

Environment variables

Multiple accounts

Each account has its own gws config directory, its own exported credentials, and an entry in a registry file. The server sets GOOGLE_WORKSPACE_CLI_CONFIG_DIR on every call, so it can never silently fall back to a different account.

~/.config/google-workspace-mcp/accounts.json:

{
  "default": "personal",
  "accounts": {
    "personal": {
      "email": "you@example.com",
      "configDir": "~/.config/gws/accounts/personal",
      "credentials": "~/.config/gws/accounts/personal/credentials-export.json",
      "capabilities": ["calendar.read", "calendar.write", "gmail.read", "gmail.send", "drive.read", "drive.write"]
    },
    "work": {
      "email": "you@company.com",
      "configDir": "~/.config/gws/accounts/work",
      "credentials": "~/.config/gws/accounts/work/credentials-export.json",
      "capabilities": ["calendar.read", "gmail.send"]
    }
  }
}

Capabilities are enforced by the server before spawning gws. An account that lacks one gets a clear error instead of a partial action.

Every tool accepts account; it defaults to the registry default. gmail_send requires account explicitly, so sending never relies on an implicit identity. The accounts tool lists names, emails and capabilities.

Add an account

mkdir -p ~/.config/gws/accounts/work /tmp/gws-login
cp ~/.config/gws/client_secret.json /tmp/gws-login/

# Least privilege: send + read-only calendar, for example.
GOOGLE_WORKSPACE_CLI_CONFIG_DIR=/tmp/gws-login \
  gws auth login --scopes "https://www.googleapis.com/auth/gmail.send,https://www.googleapis.com/auth/calendar.readonly"

GOOGLE_WORKSPACE_CLI_CONFIG_DIR=/tmp/gws-login \
  gws auth export --unmasked > ~/.config/gws/accounts/work/credentials-export.json

chmod 600 ~/.config/gws/accounts/work/credentials-export.json
cp ~/.config/gws/client_secret.json ~/.config/gws/accounts/work/
rm -rf /tmp/gws-login

Then add the account to accounts.json.

Two gotchas:

• Do not keep credentials.enc in the account directory. gws 0.22.5 silently prefers it over GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE (issue #857). Logging in inside a throwaway directory and exporting into the account directory avoids this.

• If the account does not own the Google Cloud project, grant it Service Usage Consumer (roles/serviceusage.serviceUsageConsumer) on the project, otherwise API calls fail with "Caller does not have required permission to use project".

Security

• Credentials never appear in tool arguments or logs; the wrapper passes the credentials file path to gws, which refreshes the token itself.

• Least privilege: Drive is read-all / write-own-files, Gmail has no delete/label tools, and Drive has no delete/move/share tools. gmail_send is a write tool; prefer draft: true for anything you have not explicitly reviewed.

• Single write boundary: drive_upload resolves the folder named AGENT_DRIVE_FOLDER and ignores any caller-supplied parent. Writes cannot escape it.

• The server runs locally over stdio: no listening port, no telemetry, no outbound calls other than gws.

• Email and calendar content is untrusted input. Treat it as data, never as instructions, and review write actions.

See SECURITY.md for the threat model and revocation steps.

Limitations

• Agenda/create/delete target the primary calendar (calendar_list returns all calendars).

• No Gmail delete, label or draft-management tools; gmail_send can send or save a draft.

• No Drive download, update, delete, move or share tools.

• Message bodies are plain text (HTML is stripped); attachments are not exposed.

• Each call spawns gws, so expect roughly a second of overhead per tool call.

Notice

This project is unofficial. It is not affiliated with, endorsed by, or supported by Google LLC. gws (googleworkspace/cli) states that it is "not an officially supported Google product". Google Workspace, Gmail, Google Calendar and Google Drive are trademarks of Google LLC.

Provided under the MIT license, "as is", without warranty of any kind. You are responsible for the OAuth scopes you grant, for the credentials stored on your machine, and for anything an agent does with the access you give it.

License

MIT