Google Workspace MCP — Use Cases, Install & Live Demo

Why use it

Key features

12 services in one server: Gmail, Drive, Calendar, Docs, Sheets, Slides, Forms, Tasks, Contacts, Chat, Apps Script, Custom Search
Tiered toolset (core / extended / complete) keeps the tool list manageable
OAuth 2.0 + 2.1 with multi-user bearer-token mode for hosted deployments
Stateless mode for Docker / Kubernetes
Encrypted local token cache; optional GCS-backed credential storage

Live Demo

What it looks like in practice

google-workspace-mcp.replay ▶ ready

0/0

Install

Pick your client

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "google-workspace-mcp": {
      "command": "uvx",
      "args": [
        "workspace-mcp",
        "--tool-tier",
        "core"
      ]
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "google-workspace-mcp": {
      "command": "uvx",
      "args": [
        "workspace-mcp",
        "--tool-tier",
        "core"
      ]
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "google-workspace-mcp": {
      "command": "uvx",
      "args": [
        "workspace-mcp",
        "--tool-tier",
        "core"
      ]
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "google-workspace-mcp": {
      "command": "uvx",
      "args": [
        "workspace-mcp",
        "--tool-tier",
        "core"
      ]
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "google-workspace-mcp",
      "command": "uvx",
      "args": [
        "workspace-mcp",
        "--tool-tier",
        "core"
      ]
    }
  ]
}

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

{
  "context_servers": {
    "google-workspace-mcp": {
      "command": {
        "path": "uvx",
        "args": [
          "workspace-mcp",
          "--tool-tier",
          "core"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

claude mcp add google-workspace-mcp -- uvx workspace-mcp --tool-tier core

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use Google Workspace MCP

Triage Gmail inbox to zero with Claude as your assistant

👤 Anyone with 200+ unread emails ⏱ ~25 min beginner

When to use: Monday morning and your inbox is a wall.

Prerequisites

Google Cloud OAuth client — Create OAuth 2.0 credentials in console.cloud.google.com, download client_secret.json
Server installed — uvx workspace-mcp --tool-tier core (first call opens browser for OAuth)

Flow

Bucket the inbox

Use google-workspace-mcp. List unread mail from the last 7 days. Bucket into: action-required, FYI, newsletters, automated.✓ Copied

→ Counts per bucket plus subject samples
Auto-archive low-value buckets

Archive everything in newsletters + automated. Don't touch action-required.✓ Copied

→ N archived, 0 action-required affected
Draft replies

For each action-required email, draft a 2-line reply in my voice. Save as drafts, don't send.✓ Copied

→ Drafts visible in Gmail; you tweak + send

Outcome: Inbox down to <20, replies drafted but not sent — full human review still in your hands.

Pitfalls

Granted full Gmail scope, regret it — Use --tool-tier core — no send_email tool until you opt in to extended

Combine with: filesystem

Generate a weekly status report from Calendar + Docs activity

👤 ICs and managers who write weekly updates ⏱ ~10 min beginner

When to use: Friday afternoon, you've forgotten what you did this week.

Flow

Pull calendar

Use google-workspace-mcp. List meetings I attended Mon–Fri this week (skip declined). For each, give 1-line context.✓ Copied

→ Chronological list with brief context per meeting
Pull doc activity

List Drive docs I edited or commented on this week. Group by project.✓ Copied

→ Grouped doc list with edit/comment counts
Draft the update

Combine into a 6-bullet weekly update — what I shipped, what's blocked, what's next.✓ Copied

→ Ready-to-send Slack/email draft

Outcome: A weekly update that took 3 minutes instead of 30, grounded in actual artifacts.

Pitfalls

Calendar full of recurring 1:1s clutters the report — Filter by event title patterns or attendee count — ask Claude to skip recurring 1:1s by default

Extract structured data from messy Sheets and write back results

👤 Ops, finance, anyone living in spreadsheets ⏱ ~20 min intermediate

When to use: You have a sheet with 1000 rows of free-text descriptions and need them categorized.

Flow

Read range

Use google-workspace-mcp. Read column B from Sheet 'Q4 expenses' — 1000 rows of vendor descriptions.✓ Copied

→ Rows loaded; sample shown
Categorize

Categorize each row into: SaaS, hardware, travel, services, other. Show distribution first.✓ Copied

→ Distribution table; spot-check examples
Write back

Write categories into column F. Add a header. Don't touch other columns.✓ Copied

→ Sheet updated; you verify a sample manually

Outcome: Categorized data in the sheet, audit trail in chat.

Pitfalls

Claude overwrites a column you cared about — Always specify the target column explicitly; verify a few cells before mass write

Auto-generate meeting prep docs from calendar invites

👤 Anyone with back-to-back meetings ⏱ ~15 min intermediate

When to use: You have 5 meetings tomorrow and zero context.

Flow

Scan tomorrow

Use google-workspace-mcp. List tomorrow's meetings with attendees and any attached docs.✓ Copied

→ Per-meeting block with attendees + linked docs
Generate briefs

For each, create a Doc 'Prep — <meeting title>' summarizing attached docs + suggesting 3 questions to ask.✓ Copied

→ N Docs created in /Meeting prep/ folder

Outcome: Walk into each meeting prepped, not winging it.

Pitfalls

External attendees can't see your prep doc, but a shared title might leak intent — Use a private prep folder; titles like 'Prep — <topic>' not '<sensitive deal name>'

Combinations

Pair with other MCPs for X10 leverage

google-workspace-mcp + filesystem

Sync Drive docs to local for offline editing or git tracking

Pull all docs in /weekly-updates/ from Drive into ./drive-mirror/ as markdown.✓ Copied

google-workspace-mcp + github

Mirror release notes between GitHub and a Doc

Take the latest GitHub release notes and append them to the 'Release log' Google Doc.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call	Cost
search_gmail	query: str (Gmail search syntax), max_results?	Find emails matching natural language criteria	1 Gmail API call
send_email	to, subject, body, cc?, bcc?	Only in extended/complete tier — never auto-send without confirmation	1 API call
list_calendar_events	calendar_id, time_min, time_max	Pull a date range of events	1 Calendar API call
read_sheet_range	spreadsheet_id, range (A1 notation)	Pull cells from a sheet	1 Sheets API call
write_sheet_values	spreadsheet_id, range, values[][]	Update sheet ranges with computed data	1 API call
create_doc	title, content (markdown)	Generate new docs from chat output	1 Docs API call
search_drive	query, mime_type?	Locate files by name/content	1 Drive API call

Cost & Limits

What this costs to run

API quota: Gmail: 250 quota units/user/sec; Calendar: 500 req/100sec; Sheets: 300 req/min/user
Tokens per call: 200–4000 depending on call (full email body vs metadata)
Monetary: Free for personal Google accounts; Workspace orgs may have admin restrictions
Tip: Use --tool-tier core unless you actually need Forms/Slides/Apps-Script — fewer tools = smaller system prompt

Security

Permissions, secrets, blast radius

Minimum scopes: gmail.readonly calendar.readonly drive.readonly

Credential storage: Encrypted local token cache by default; optional GCS-backed for hosted

Data egress: Direct to googleapis.com — no third-party relay

Never grant: gmail.send (until you understand the auto-send risk) drive (full read/write everywhere)

OAuth 2.0 + 2.1 supported; pick PKCE public client unless you have a confidential client setup

Troubleshooting

Common errors and fixes

OAuth callback fails / browser doesn't open

Set OAUTH_REDIRECT_PORT to an open port and re-run; on headless boxes use device-flow mode

Verify: lsof -i :8080 to confirm port free

403 insufficient_permissions

Re-auth with the missing scope; check that your OAuth client allowed it in Google Cloud Console

Verify: Decode token at oauth2.googleapis.com/tokeninfo to see granted scopes

Workspace admin blocks the OAuth client

Have the admin add your client ID to the trusted apps list, or use a personal Google account for testing

Quota exceeded on bulk operations

Add backoff; the server respects Retry-After headers but bulk loops can still trip per-second limits

Verify: Watch for HTTP 429 in logs

Alternatives

Google Workspace MCP vs others

Alternative	When to use it instead	Tradeoff
Pipedream MCP	You want managed OAuth + ready-made Google integrations without self-hosting	Costs money at scale; data flows through Pipedream
Per-service MCP servers (gmail-mcp, drive-mcp)	You only need one Google service and want minimal scope surface	Multiple OAuth flows + token caches to manage

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills