google-workspace-mcp

mcp-google-workspace

Production-ready 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 credentials.json in one of:

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

On first run, the server launches a browser for OAuth consent and writes token.json.

Optional service feature flags

Sheets, Docs, Tasks, People, Forms, and Slides are mounted by default and their scopes are always requested. If you are upgrading from an older checkout, delete token.json once so OAuth can re-consent the expanded scope set.

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 one of these optional integrations or otherwise change the scope set, delete token.json and re-authenticate to refresh granted scopes.

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)

This repository now includes a native uv-based MCP Bundle manifest and packaging assets.

Install on Claude Desktop:

1. Download the latest .mcpb from GitHub Releases.
2. In Claude Desktop, open the MCP bundle install flow.
3. Select the downloaded mcp-google-workspace-*.mcpb file.
4. Choose the credentials directory that contains credentials.json, or leave it empty to use the repo defaults.
5. Enable optional integrations only if your Google Workspace account and OAuth client support their scopes.
6. Finish the install and authenticate in the browser on first launch.