@jbctechsolutions/mcp-google-workspace

MCP server for Google Workspace — a Gmail read + label slice (v0.1): search messages, read them, list/download attachments, list labels, and add/remove labels.

A Model Context Protocol (MCP) server that exposes 6 tools over the Gmail API. No send, no delete, no draft — by design. When write tools arrive later they will use mcp-office365's prepare_/confirm_ two-phase naming.

Tools

| Tool | Description | |------|-------------| | search_emails | Search with a Gmail query; returns from/subject/date/labels/snippet per hit | | get_email | One message by ID: headers, decoded text/HTML body, attachment metadata | | list_attachments | Attachment metadata (filename, mime, size, attachment ID) for a message | | download_attachment | Save one attachment to an absolute path (guarded — see below) | | list_labels | All labels (system + user) with IDs and message counts | | modify_email_labels | Add and/or remove labels on a message (the only write in v0.1) |

download_attachment guardrails: absolute path required, never overwrites (including symlinks), 32MB cap (matches Mercury's attachment limit), verifies the downloaded bytes match the output file's extension (%PDF, PNG/JPG/GIF/HEIC signatures), and refuses executable/script extensions.

Authentication

Auth uses a Google Cloud Internal OAuth app (no verification, no CASA, no 7-day refresh-token expiry — those only apply to External apps) with the single scope https://www.googleapis.com/auth/gmail.modify (covers read, attachment download, and label changes; not permanent delete, not send).

One-time setup (operator)

1. GCP project + API. Use the jbc-tech-solutions project (org joelbcastillo.com, which contains the jbc.dev domain). The Gmail API is already enabled there (enabled 2026-07-07). If starting fresh elsewhere: APIs & Services → Library → Gmail API → Enable.

2. OAuth consent screen. APIs & Services → OAuth consent screen → User type: Internal → fill app name/support email → add the scope .../auth/gmail.modify → Save.

3. OAuth client. APIs & Services → Credentials → Create Credentials → OAuth client ID → Application type Desktop app → Create. Copy the Client ID and Client secret.

4. 1Password item. Create an item named Google Workspace MCP OAuth in the jbctechsolutions.1password.com account with:

   • the Client ID in a field labelled username
   • the Client secret in a field labelled credential

5. Sign in once. With the 1Password CLI signed in (op signin --account jbctechsolutions.1password.com), run:

   mcp-google-workspace auth        # opens a browser to grant access
   mcp-google-workspace auth --status
   mcp-google-workspace auth --logout

   The refresh token is written 0600 to ~/.config/mcp-google-workspace/token.json — outside any repo. The client id/secret are re-resolved from 1Password on each run and are never stored in that file. googleapis auto-refreshes access tokens from the refresh token; if Google ever returns invalid_grant, re-run mcp-google-workspace auth.

1Password item contract

| Field label | Holds | |-------------|-------| | username | OAuth Client ID | | credential | OAuth Client secret |

(Item name and field labels are overridable — see the env table.)

Environment overrides

| Variable | Default | Purpose | |----------|---------|---------| | GOOGLE_WS_CLIENT_ID | — | Bypass 1Password for the client id (tests/CI) | | GOOGLE_WS_CLIENT_SECRET | — | Bypass 1Password for the client secret (tests/CI) | | GOOGLE_WS_OP_ACCOUNT | jbctechsolutions.1password.com | 1Password account | | GOOGLE_WS_OP_ITEM | Google Workspace MCP OAuth | 1Password item name | | GOOGLE_WS_OP_CLIENT_ID_FIELD | username | Field label for the client id | | GOOGLE_WS_OP_CLIENT_SECRET_FIELD | credential | Field label for the client secret | | GOOGLE_WS_TOKEN_PATH | ~/.config/mcp-google-workspace/token.json | Refresh-token file (0600, outside any repo) |

Both GOOGLE_WS_CLIENT_ID and GOOGLE_WS_CLIENT_SECRET must be set to skip 1Password; setting only one falls back to 1Password.

Quick start

npm install
npm run build
mcp-google-workspace auth   # once, after the GCP + 1Password setup above

Claude Code / Claude Desktop configuration

{
  "mcpServers": {
    "google-workspace": {
      "command": "node",
      "args": ["/path/to/mcp-google-workspace/dist/index.js"]
    }
  }
}

(Once published: npx -y @jbctechsolutions/mcp-google-workspace. npm publish and Claude-plugin packaging follow mcp-office365's pattern when the server matures — deferred.)

The 1Password CLI must be installed and signed in to the jbctechsolutions account for client-credential resolution to work, and mcp-google-workspace auth must have been run once.

Development

npm test          # vitest unit tests (all network/1Password/fs mocked)
npm run typecheck # tsc --noEmit
npm run build     # compile to dist/

License

MIT © JBC Tech Solutions, LLC