# Google Workspace MCP Server

A [MCP](https://modelcontextprotocol.io) server built with [FastMCP](https://gofastmcp.com) for Google Workspace with **multi-account support**. Works with Claude Desktop, Claude Code, or any MCP client to interact with Gmail, Google Drive, Sheets, and Calendar across multiple Google accounts.

## Features

- **Multi-account profiles** — Named profiles (e.g. `business`, `personal`) to switch between accounts
- **Zero-friction setup** — OAuth flows triggered from within Claude, no CLI needed
- **Gmail** — Search, read, send, threads, attachments (5 tools)
- **Google Drive** — Upload, download, list, search, folders, move, trash (7 tools)
- **Google Sheets** — Read, write, append, create, metadata (5 tools)
- **Google Calendar** — Events, create/update/delete, free/busy, calendars (6 tools)
- **28 tools total** including 4 auth/setup tools
- **Clean architecture** — Services layer (Google API) separated from tools layer (MCP)

## Prerequisites

A **Google Cloud Project** with OAuth 2.0 credentials:
1. Go to [Google Cloud Console → Credentials](https://console.cloud.google.com/apis/credentials)
2. Create an **OAuth 2.0 Client ID** (type: **Desktop app**)
3. Enable these APIs in [API Library](https://console.cloud.google.com/apis/library):
   Gmail API, Google Drive API, Google Sheets API, Google Calendar API

That's it. No redirect URIs to configure — the server handles it.

## Quick Start (Claude Desktop)

Add to your Claude Desktop config:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "google-workspace": {
      "command": "uvx",
      "args": ["multi-gw-mcp"]
    }
  }
}
```

Restart Claude Desktop. That's it — no `pip install`, no venv. `uvx` pulls from PyPI and handles everything.

> **Requires [uv](https://docs.astral.sh/uv/getting-started/installation/)** — install with `curl -LsSf https://astral.sh/uv/install.sh | sh` (Mac/Linux) or `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"` (Windows)

## Quick Start (Claude Code)

```bash
claude mcp add google-workspace -- uvx multi-gw-mcp
```

## Setup Flow (happens inside Claude)

Once the server is running, Claude handles everything:

1. **Claude calls `check_setup_status`** → sees "not configured"
2. **You provide** your Google Cloud Client ID and Secret
3. **Claude calls `setup_google_workspace`** → config saved automatically
4. **Claude calls `authenticate_account("business")`** → your browser opens to Google sign-in → you click Allow → token saved
5. **Claude calls `authenticate_account("personal")`** → same for second account
6. **Done.** All 28 tools work. Tokens auto-refresh.

No terminal commands. No config files to hand-edit. No copy-pasting tokens.

## From Local Source (Development)

If running from a local clone instead of PyPI:

```json
{
  "mcpServers": {
    "google-workspace": {
      "command": "uvx",
      "args": ["--from", "/path/to/multi-gw-mcp", "multi-gw-mcp"]
    }
  }
}
```

## Usage

Every tool accepts an optional `profile` parameter. If omitted, the first profile is used.

```
# Search business Gmail
gmail_search(query="from:aws subject:invoice after:2025/04/01", profile="business")

# Search personal Gmail
gmail_search(query="from:cloudflare invoice", profile="personal")

# Upload to Drive
drive_upload(local_path="/tmp/report.xlsx", folder_id="abc123", profile="business")

# Read a Google Sheet
sheets_read(spreadsheet_id="abc123", range="Sheet1!A1:D10")

# Check calendar
calendar_list_events(time_min="2025-04-01T00:00:00Z", time_max="2025-04-02T00:00:00Z")
```

## All Tools (28)

| Category | Tool | Description |
|----------|------|-------------|
| **Setup** | `check_setup_status` | Check config & auth status |
| **Setup** | `setup_google_workspace` | Save OAuth credentials + profiles |
| **Setup** | `authenticate_account` | Open browser OAuth for a profile |
| **Setup** | `add_google_profile` | Add another account to config |
| **Profiles** | `list_google_profiles` | List accounts & auth status |
| **Gmail** | `gmail_search` | Search with Gmail query syntax |
| **Gmail** | `gmail_read` | Read a message by ID |
| **Gmail** | `gmail_read_thread` | Read entire thread |
| **Gmail** | `gmail_send` | Send email or reply |
| **Gmail** | `gmail_get_attachment` | Download attachment |
| **Drive** | `drive_list` | List/search files |
| **Drive** | `drive_upload` | Upload local file |
| **Drive** | `drive_upload_base64` | Upload from base64 data |
| **Drive** | `drive_download` | Download file |
| **Drive** | `drive_create_folder` | Create folder |
| **Drive** | `drive_move` | Move between folders |
| **Drive** | `drive_trash` | Trash a file |
| **Sheets** | `sheets_read` | Read data from range |
| **Sheets** | `sheets_write` | Write data to range |
| **Sheets** | `sheets_append` | Append rows |
| **Sheets** | `sheets_create` | Create spreadsheet |
| **Sheets** | `sheets_info` | Get metadata |
| **Calendar** | `calendar_list_events` | List events |
| **Calendar** | `calendar_create_event` | Create event |
| **Calendar** | `calendar_update_event` | Update event |
| **Calendar** | `calendar_delete_event` | Delete event |
| **Calendar** | `calendar_free_busy` | Check availability |
| **Calendar** | `calendar_list_calendars` | List calendars |

## Architecture

```
src/google_workspace_mcp/
├── server.py          # FastMCP composition + middleware
├── auth/
│   ├── oauth.py       # OAuth2 + profiles + auto-setup + browser auth flow
│   └── setup.py       # Optional CLI fallback (gw-mcp-auth)
├── services/          # Google API wrappers (reusable, testable)
│   ├── gmail.py
│   ├── drive.py
│   ├── sheets.py
│   └── calendar.py
├── tools/             # FastMCP @mcp.tool decorated functions
│   ├── profiles.py    # Setup + auth + profile tools
│   ├── gmail.py
│   ├── drive.py
│   ├── sheets.py
│   └── calendar.py
└── middleware/
    └── error_handler.py   # Google API errors → friendly messages
```

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `GW_MCP_CONFIG_DIR` | `~/.config/google-workspace-mcp` | Config & token directory |
| `GW_MCP_OAUTH_PORT` | `3456` | Local port for OAuth callback |

## Optional CLI

If you prefer terminal setup over in-chat setup:

```bash
uvx --from multi-gw-mcp gw-mcp-auth --init       # Create config interactively
uvx --from multi-gw-mcp gw-mcp-auth --profile biz # Auth one profile
uvx --from multi-gw-mcp gw-mcp-auth --status      # Check status
```

## Built With

- [FastMCP](https://gofastmcp.com) — Python MCP framework
- [Google API Python Client](https://github.com/googleapis/google-api-python-client)
- [uv](https://docs.astral.sh/uv/) — Fast Python package management

## License

MIT
