google-workspace

mcp-google-workspace

Production-oriented Google Workspace MCP package with:

• Gmail MCP: send/read/search emails, attachment handling, label management, batch operations.
• Google Calendar MCP: events, availability, create/update/delete operations.
• Google Drive MCP: files/folders CRUD, uploads/downloads/exports, sharing permissions, Shared Drives operations.
• Google Sheets MCP: spreadsheet metadata, values reads/writes, and raw batch updates.
• Google Docs MCP: document fetch/create flows plus convenience text mutations and raw batch updates.
• Google Tasks MCP: task lists, tasks, completion, movement, and deletion.
• Google People MCP: personal contacts and contact groups.
• Google Forms MCP: forms CRUD, publish settings, and response reads.
• Google Slides MCP: presentations, slide pages, thumbnails, text replacement, and raw batch updates.
• MCP Apps Dashboard: workspace dashboard app-layer tools/resources with interactive UI.
• Optional Google Keep MCP, Google Chat MCP, Google Meet MCP, and Gemini media integrations behind feature flags.
• FastMCP advanced features: Context logging, progress updates, user elicitation, sampling, resources, and prompts.
• Composed server architecture: Gmail + Calendar + Drive + Sheets + Docs + Tasks + People + Forms + Slides mounted by default, with optional Apps/Keep/Chat/Meet/Gemini namespaces.

Requirements

• Python 3.12+
• UV package manager
• Node.js 18+ and npm (required for MCP Apps UI in src/mcp_google_workspace/apps/ui)
• Google Cloud OAuth desktop credentials (credentials.json)
• Google APIs enabled in your Google Cloud project: Gmail, Calendar, Drive, Sheets, Docs, Tasks, People, Forms, and Slides
• Optional APIs when enabling feature-flagged integrations: Google Keep, Google Chat, and Google Meet
• Gemini Developer API key when enabling Gemini media tools

Installation

uv sync --all-extras --dev

If you are working on MCP Apps UI, install frontend dependencies and build the bundle:

cd src/mcp_google_workspace/apps/ui
npm ci
npm run build

OAuth setup

Place the Google OAuth client credentials.json in one of:

• project root: ./credentials.json
• package credentials folder: ./src/credentials/credentials.json

Configure a versioned Fernet key ring before first use. Production deployments should mount a secret-manager document through MCP_SECRET_FILE; MCP_TOKEN_ENCRYPTION_KEY remains a single-key development option. The MCP encrypts each user's refresh token separately and never writes a shared token.json.

Generate a key once and store it in your secret manager:

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Mounted secret document:

{
  "active_token_encryption_key_id": "2026-07",
  "token_encryption_keys": {
    "2026-07": "<active Fernet key>",
    "2026-04": "<retained previous Fernet key>"
  }
}

Reads accept retained keys and rewrite ciphertext with the active key. Remove an old key only after a rotation/restore drill confirms all durable records have been rewritten.

Optional service feature flags

Sheets, Docs, Tasks, People, Forms, and Slides are mounted by default and their scopes are always requested. When scopes change, reconnect the affected user so their encrypted per-user token receives the expanded grant.

Google Keep OAuth scope can return invalid_scope in standard user OAuth flows. Keep integration is therefore disabled by default.

Enable Keep when your Google Workspace setup supports it:

$env:ENABLE_KEEP="true"

Google Chat OAuth scopes also commonly require Google Workspace accounts. Chat integration is therefore disabled by default.

Enable Chat when your Google Workspace setup supports it:

$env:ENABLE_CHAT="true"

Google Meet integration is also disabled by default. Enable it only after enabling the Meet API for the same OAuth client:

$env:ENABLE_MEET="true"

Gemini media integration is also disabled by default. Enable it with a Gemini Developer API key:

$env:ENABLE_GEMINI="true"
$env:GEMINI_API_KEY="your-api-key"

Capability-specific Gemini model defaults:

$env:GEMINI_IMAGE_GENERATE_MODEL="gemini-3.1-flash-image-preview"
$env:GEMINI_IMAGE_EDIT_MODEL="gemini-3.1-flash-image-preview"
$env:GEMINI_VIDEO_UNDERSTANDING_MODEL="gemini-3-flash-preview"
$env:GEMINI_AUDIO_UNDERSTANDING_MODEL="gemini-3-flash-preview"
$env:GEMINI_REASONING_MODEL="gemini-3.1-pro-preview"

Whenever you enable an optional integration or otherwise change scopes, reconnect each affected user.

Apps dashboard rollout flag

The MCP app-layer dashboard namespace is opt-in for controlled rollout.

Enable apps namespace:

$env:ENABLE_APPS_DASHBOARD="true"

Run (STDIO)

uv run python -m mcp_google_workspace

MCP Bundle (MCPB)