Google Workspace MCP Server

A personal MCP server giving AI assistants natural-language control over Gmail, Drive, Calendar, Docs, and Sheets.

What It Does

This server connects AI assistants to five Google Workspace services (Gmail, Drive, Calendar, Docs, Sheets) — 70+ tools behind a single MCP server, with OAuth 2.1 multi-user auth, three progressive tool tiers, read-only mode, a full CLI, and stateless container deployment. It runs locally over stdio for legacy clients and remotely over streamable HTTP with full implementation of the latest MCP spec.

Related MCP server: google-cli-mcp

Services

Quick Start

You'll need an OAuth client from Google Cloud Console with the relevant APIs enabled (Gmail, Drive, Calendar, Docs, Sheets).

# 1. Credentials
export GOOGLE_OAUTH_CLIENT_ID="..."
export GOOGLE_OAUTH_CLIENT_SECRET="..."

# 2. Run it (from a clone of this repo)
uv run main.py --tool-tier core       # essential tools
uv run main.py --tool-tier extended   # core + management ops
uv run main.py --tool-tier complete   # everything

# Or cherry-pick services
uv run main.py --tools gmail drive calendar

Tool tiers keep context windows lean: core is the essential set, extended adds management operations, complete loads everything. Combine with --tools <service> ..., --read-only, or per-service --permissions.

Connect Your Client

Point any MCP client (Claude Desktop/Code, VS Code, etc.) at this server. For local stdio clients, add an entry like:

{
  "mcpServers": {
    "google-workspace": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/this/repo", "main.py"]
    }
  }
}

For remote/HTTP clients, run uv run main.py --transport streamable-http and connect over http://localhost:8000/mcp.

CLI

workspace-cli lists and calls tools against a running server with encrypted, disk-backed OAuth token caching:

uv run workspace-cli list
uv run workspace-cli call search_gmail_messages query="is:unread" max_results=5

Security Notes

• Prompt injection is real. Emails, docs, and events can contain hidden instructions. Only connect trusted data to an LLM, and be deliberate about which write tools you enable.

• Never commit .env, client_secret.json, or .credentials/ to source control.

• Local file reads are sandboxed to the managed attachment directory. Broaden with ALLOWED_FILE_DIRS only if you trust the client and its data sources; .env*, ~/.ssh/, ~/.aws/, and similar paths are always blocked.

• Production deployments should use HTTPS and OAuth 2.1.

Development

uv sync --group dev    # install deps
uv run ruff check .    # lint
uv run pytest          # test

Single-file service modules live in gmail/, google_drive/, google_calendar/, google_docs/, google_sheets/; tools are registered with @server.tool decorators, and tiers are defined in core/tool_tiers.yaml.

License

MIT - see LICENSE.