google_workspace_mcp MCP — Use Cases, Install & Live Demo

Why use it

Key features

11 services in one server: Gmail, Drive, Calendar, Docs, Sheets, Slides, Forms, Tasks, Contacts, Chat, Apps Script
Tool tiers (core/extended/complete) to shrink the tool list for cheaper prompts
OAuth 2.0 via your own Google Cloud credentials — no third-party broker
Supports stdio + HTTP MCP transports
Streamable outputs for long doc / sheet reads

Live Demo

What it looks like in practice

google-workspace.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": {
      "command": "uvx",
      "args": [
        "google_workspace_mcp"
      ],
      "_inferred": true
    }
  }
}

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

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

{
  "mcpServers": {
    "google-workspace": {
      "command": "uvx",
      "args": [
        "google_workspace_mcp"
      ],
      "_inferred": true
    }
  }
}

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

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "google-workspace": {
      "command": "uvx",
      "args": [
        "google_workspace_mcp"
      ],
      "_inferred": true
    }
  }
}

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

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "google-workspace": {
      "command": "uvx",
      "args": [
        "google_workspace_mcp"
      ],
      "_inferred": true
    }
  }
}

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

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "google-workspace",
      "command": "uvx",
      "args": [
        "google_workspace_mcp"
      ]
    }
  ]
}

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

~/.config/zed/settings.json

{
  "context_servers": {
    "google-workspace": {
      "command": {
        "path": "uvx",
        "args": [
          "google_workspace_mcp"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

claude mcp add google-workspace -- uvx google_workspace_mcp

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

Use Cases

Real-world ways to use google_workspace_mcp

How to triage your inbox to zero with AI labels and drafts

👤 Knowledge workers, execs ⏱ ~20 min intermediate

When to use: Monday morning or post-vacation when your inbox is a war zone.

Prerequisites

Google Cloud project with Gmail API enabled — console.cloud.google.com > APIs > Gmail API > Enable
OAuth 2.0 Desktop credentials — Credentials > Create OAuth client > Desktop. Set GOOGLE_OAUTH_CLIENT_ID and _SECRET env vars

Flow

Pull last week of unread

Search Gmail for unread messages from the last 7 days. Group by sender category (team, external, vendor, newsletter).✓ Copied

→ Grouped counts + preview lines
Auto-label + archive newsletters

For the newsletter bucket, label them 'newsletter' and archive.✓ Copied

→ Count archived, thread ids
Draft replies to the top-5 real threads

For the 5 most important threads (client ask, blocker, decision needed), draft a concise reply. Do not send — just draft.✓ Copied

→ 5 drafts visible in Gmail

Outcome: Inbox under 20, drafts ready to review + send.

Pitfalls

AI sends replies instead of drafting — Always say 'draft only' in the prompt; disable send_gmail_message for untrusted sessions

Combine with: notion

How to prep for every meeting tomorrow from your calendar

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

When to use: EOD before a heavy day.

Flow

List tomorrow's events

Get my calendar events for tomorrow. For each, show attendees and the meeting title.✓ Copied

→ Timeline of events
For each meeting, find linked doc and recent emails

For every meeting with an agenda link, open the doc and summarize. For each attendee, show the last email thread with them.✓ Copied

→ Per-meeting brief
Dump into one doc

Create a Doc 'Prep 2026-04-15' with a section per meeting.✓ Copied

→ Doc URL returned

Outcome: A single prep doc you can skim over coffee.

Pitfalls

External attendees' emails have PII — they go to your LLM provider — Strip to names only in prompts if you care

Combine with: notion

How to turn a Google Sheet into a read/write data source for agents

👤 Ops people running business processes on Sheets ⏱ ~15 min intermediate

When to use: You don't want to migrate to a real DB yet but want AI to answer questions + log events.

Flow

Describe the sheet layout

Read tab 'Orders' in spreadsheet 1AbC... — tell me the schema.✓ Copied

→ Column list with types
Answer a question

Using read_sheet_values, how many orders in March were over $1000?✓ Copied

→ Numeric answer + cells consulted
Append a row

Append a new row: today's date, customer=acme, amount=1200, status=pending.✓ Copied

→ Appended row index

Outcome: Ad-hoc analytics + logging without leaving chat.

Pitfalls

Formulas recompute on write and may overwrite cells you care about — Use append_table_rows, not range writes, when adding data

Combine with: filesystem

How to generate a Google Doc from a markdown template

👤 Anyone generating proposals, reports, or templated docs ⏱ ~10 min beginner

When to use: You want rich Docs output (tables, headers) without learning Google's API.

Flow

Draft in markdown

Write a client proposal for ACME based on [brief]. Output as markdown.✓ Copied

→ Markdown draft
Convert to Doc

Create a new Google Doc titled 'ACME Proposal 2026-04' with that content. Use create_doc then batch_update_doc to preserve formatting.✓ Copied

→ Doc URL

Outcome: A properly-formatted Doc you can share.

Pitfalls

create_doc only takes plain text — formatting needs a follow-up batch_update — Always use the two-step flow for rich docs

Combinations

Pair with other MCPs for X10 leverage

google-workspace + notion

Mirror meeting prep docs into Notion for team visibility

For each meeting today, copy the Google Doc agenda into a new Notion page under 'Meeting Notes' with the date as title.✓ Copied

google-workspace + filesystem

Export a Drive folder to local disk as a backup

Download every file in Drive folder 'Client Contracts 2025' to /backups/drive/contracts-2025/.✓ Copied

google-workspace + github

Cross-reference GitHub issues with calendar standups

Before my 10am standup, list open GitHub issues assigned to me and attach the summary to today's standup event description.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call	Cost
search_gmail_messages	query: str, max_results?: int	Find messages by sender, subject, date	1 Gmail API call
draft_gmail_message	to, subject, body, thread_id?	Prefer draft over send for AI workflows	1 API call
send_gmail_message	to, subject, body	Only when user explicitly asks to send	1 API call (irreversible)
get_events	calendar_id?, time_min, time_max	Pull events in a window	1 Calendar API call
manage_event	action, event_id?, summary?, attendees?, time?	Create/update/delete events	1 API call
read_sheet_values	spreadsheet_id, range	Read a cell range	1 Sheets API call
append_table_rows	spreadsheet_id, table_id, rows	Safe append without overwriting formulas	1 Sheets API call
create_doc	title, content?	Start a new doc	1 Docs API call
batch_update_doc	doc_id, requests[]	Apply formatting after create_doc	1 Docs API call (batched)
search_drive_files	query, max_results?	Locate a file by name/owner	1 Drive API call

Cost & Limits

What this costs to run

API quota: Gmail: 250 quota units/user/sec. Sheets: 300 reads/min/user. Drive: 1000 queries/100s/user.
Tokens per call: Tool list at 'complete' tier is huge (~100 tools); use 'core' tier to stay cheap
Monetary: Free with a Google account
Tip: Run with --tool-tier core and switch to extended only when you actually need Slides/Forms/Script.

Security

Permissions, secrets, blast radius

Minimum scopes: Only grant the scopes for the services you actually use (e.g. gmail.readonly, calendar.readonly)

Credential storage: GOOGLE_OAUTH_CLIENT_ID/_SECRET in env; refresh tokens persisted on disk

Data egress: Your doc/email contents go through the MCP server to your chosen LLM provider

Never grant: gmail.send if you don't need to send drive (full) if drive.file suffices admin scopes

OAUTHLIB_INSECURE_TRANSPORT=1 is for localhost dev only — never set it on a hosted instance.
Desktop OAuth clients cannot be used for production web deployments; use a Web client there.

Troubleshooting

Common errors and fixes

invalid_grant / token has been expired or revoked

Delete the cached token file and re-run auth flow.

Verify: ls ~/.config/google_workspace_mcp/tokens

403 insufficient permission

Re-consent with the needed scope — the stored token doesn't have it yet.

API not enabled

Enable the specific API (e.g. Docs API) in Google Cloud Console for your project.

Quota exceeded for user

Gmail and Sheets have per-minute caps. Batch reads; back off with exponential retry.

Alternatives

google_workspace_mcp vs others

Alternative	When to use it instead	Tradeoff
Official Gmail MCP (Anthropic remote)	You want Anthropic-hosted OAuth with zero setup	Gmail only; no Drive/Docs/Sheets
zapier MCP	You already pay for Zapier and want zero config	Costs money per call; latency higher

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills