google-workspace-mcp

Five isolated remote MCP services for Gmail, Google Calendar, Google Drive, Google Sheets, and Google Docs. Each service runs as a separate process with its own endpoint, OAuth state, Google credential, scope set, and tool registry.

Status: pre-alpha. All five service processes and 55 service-owned tools are locally runnable. The deployed revision runs as five isolated loopback services behind the public HTTPS vhost; production Google credentials remain server-only and are never included in the repository.

Public pages

• Homepage

• Google user data privacy policy

The public HTTPS surface serves the homepage and privacy policy together with five path-scoped MCP and OAuth runtime surfaces.

Included

• Five independent Streamable HTTP MCP service entry points

• OAuth 2.1 client authorization with PKCE S256

• Resource-bound bearer tokens and rotating refresh tokens

• Replay detection and refresh-family revocation

• Five isolated Google credential stores

• Exact per-service Google OAuth scope validation

• Public health and protected readiness endpoints

• Fail-closed service and resource ownership checks

• Exact trusted-proxy allowlists

• Secret-safe provider error boundaries

• Managed Gmail attachment and Drive download storage

• OAuth state administration CLI

• Google installed-application authorization CLI

• Cross-service cutover safety and state transition CLI

• A hardened systemd template, five isolated environment examples, and active, maintenance, candidate, and bootstrap nginx assets

Service capabilities

Detailed tool names, limits, concurrency, continuation, and error behavior are documented in Google Workspace integrations.

Documentation

• Architecture overview

• Google Cloud and OAuth setup

• Authentication and credential operations

• Google Workspace integrations

• MCP protocol contract

• Production deployment

Architecture

The project separates two authorization layers:

1. An MCP client authenticates to one service through OAuth 2.1.

2. That service authenticates to one Google product API through its own Google credential.

Google credentials never cross the MCP boundary. An MCP bearer token is accepted only by the canonical protected MCP resource that issued it.

Each process owns its MCP endpoint, Google scopes, Google credential, downstream OAuth state, audit target, managed-file directory, and tool registry.

See Architecture overview for the complete data flow and source layout.

Technology

• Python 3.14

• uv

• MCP Python SDK

• Starlette

• Pydantic

• Google API Python Client

Prerequisites

• Python 3.14

• uv

• A Google Cloud project

• A Desktop OAuth client

• A public HTTPS service URL

See Google Cloud and OAuth setup before creating service credentials.

Development setup

git clone https://github.com/hawkxdev/google-workspace-mcp.git
cd google-workspace-mcp
uv sync --dev

The virtual environment does not need to be activated. Run project commands through uv run.

Testing

uv run --no-sync pytest -q
uv run --no-sync ruff check .
uv run --no-sync ruff format --check .
uv run --no-sync mypy src

The suite runs without network access, Google credentials, or a database. Provider calls are covered by transport doubles, so a test that reaches the network is a defect rather than an environment problem.

Runtime configuration

Every service reads variables with its uppercase prefix:

GMAIL_
CALENDAR_
DRIVE_
SHEETS_
DOCS_

<SERVICE> below means one of those five prefixes.

The public URL must be an absolute HTTPS URL identifying the service-base issuer (for example https://mcp.hawkxdev.dev/gmail). The canonical protected MCP resource (/<service>/mcp), OAuth metadata, bearer-token resource binding, and advertised endpoints are derived from it.

One example file per service is available under deploy/env/: gmail.env.example, calendar.env.example, drive.env.example, sheets.env.example, and docs.env.example. Copy the one you need and fill in the required values.

OAuth state, Google credentials, audit logs, and managed downloads must use distinct paths.

MCP_FORWARDED_ALLOW_IPS accepts only explicit trusted proxy addresses or bounded networks. Wildcards and unbounded networks are rejected.

Default service endpoints

Each entry point requires its complete service-prefixed configuration before startup.

Google authorization

Each service requires a separate Google OAuth grant.

uv run --no-sync google-mcp-authorize --service gmail --client-secrets "$HOME/.local/share/google-workspace-mcp/client_secret.json"

The command requests offline access and rejects grants without a refresh token or the complete service scope set.

See Google Cloud and OAuth setup for API enablement, scopes, consent, publishing, verification, credential permissions, and troubleshooting.

MCP client authorization

Each service exposes OAuth 2.1 discovery, dynamic client registration, authorization-code exchange, rotating refresh tokens, and resource-bound bearer access.

See Authentication and credential operations for client authorization, token lifecycle, revocation, and backup commands.

OAuth administration

List one service's registered clients:

uv run --no-sync google-mcp-oauth --service gmail clients list

The CLI can list and revoke clients or access tokens and create online OAuth state backups. It returns metadata only, never token values or client secrets.

Source layout

src/google_workspace_mcp/
├── auth/
├── audit/
├── cli/
├── common/
├── google_auth/
├── services/
└── transport/

deploy/
├── README.md
├── check-cutover-ingress.sh
├── env/
├── google-mcp@.service
├── nginx-google-workspace-mcp-active.inc
├── nginx-google-workspace-mcp-bootstrap.conf
├── nginx-google-workspace-mcp-candidate.conf
├── nginx-google-workspace-mcp-maintenance.inc
├── nginx-google-workspace-mcp.conf
└── public/
docs/
├── overview.md
├── google-cloud-setup.md
├── auth.md
├── integrations.md
└── protocol.md

Current boundaries

• The deployed revision runs through one systemd template and five isolated instances.

• Production Google credentials are stored only in per-service owner-only files on the managed host.

• The homepage, privacy policy, MCP routes, OAuth routes, metadata, health, and readiness share one HTTPS vhost without sharing process state.

• Google OAuth publishing and verification are separate states.

• Restricted Google scopes may require verification and a security assessment.

• Refresh tokens can be revoked or invalidated by Google.

• The project calls stable Gmail, Calendar, Drive, Sheets, and Docs APIs directly.

• Google Developer Preview MCP endpoints are not runtime dependencies.

• Irreversible Gmail deletion is not supported.

• Full Calendar administration and permission management are not supported.

• Raw Google request mappings and arbitrary provider field masks are not public tool inputs.

Contributing

The project is published as a working reference rather than as a product seeking contributors, so open an issue before writing code: a change that does not fit the service isolation model is expensive to review and unlikely to land.

A pull request is expected to keep the checks below green and to explain which behavior changed and how that change was proven:

uv run --no-sync pytest -q
uv run --no-sync ruff check .
uv run --no-sync ruff format --check .
uv run --no-sync mypy src

Two boundaries are not negotiable. Google credentials, OAuth state, audit logs, and managed downloads keep separate paths and never cross the MCP boundary. Real account identifiers, addresses, tokens, and user content never enter the repository, tests, or fixtures.

Report anything that looks like a credential exposure privately through a GitHub security advisory on this repository instead of opening a public issue.

Maintainers

• @hawkxdev

License and provenance

The project is licensed under MIT. Its OAuth 2.1 core adapts the public obsidian-web-mcp project; copyright and attribution details are recorded in NOTICE.