# Google Workspace MCP

A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes **55 tools across 9 Google Workspace services** — Calendar, Gmail, Drive, Docs, Sheets, Slides, Tasks, Forms, and Keep.

Authentication uses a **service account with domain-wide delegation**, impersonating a Workspace user. No interactive OAuth flow is needed at runtime — ideal for headless agents and automation.

## Tool inventory

| Service | Tools | Examples |
|---|---|---|
| **Calendar** (7) | `list_calendars`, `list_calendar_events`, `create_calendar_event`, `update_calendar_event`, `delete_calendar_event`, `search_calendar_events`, `get_free_busy` | Create/update events, free/busy lookup |
| **Gmail** (11) | `list_gmail_labels`, `search_gmail`, `read_gmail_message`, `list_gmail_attachments`, `download_gmail_attachments`, `send_gmail`, `reply_to_gmail`, `create_gmail_draft`, `mark_gmail_read`, `mark_gmail_unread`, `delete_gmail_message` | Full mail workflow incl. attachments & "Send mail as" aliases |
| **Drive** (8) | `search_drive_files`, `read_drive_file`, `create_drive_folder`, `share_drive_file`, `upload_drive_file`, `delete_drive_file`, `rename_drive_file`, `move_drive_file` | Upload text via `content` or binary via `local_path` |
| **Docs** (5) | `read_google_doc`, `create_google_doc`, `append_to_google_doc`, `replace_text_in_google_doc`, `delete_google_doc` | |
| **Sheets** (6) | `read_google_sheet`, `write_google_sheet`, `append_to_google_sheet`, `create_google_sheet`, `clear_google_sheet`, `add_sheet_tab` | |
| **Slides** (5) | `read_google_slides`, `create_google_slides`, `add_slide_with_text`, `delete_slide`, `update_slide_text` | |
| **Tasks** (7) | `list_task_lists`, `list_tasks`, `create_task`, `complete_task`, `delete_task`, `update_task`, `create_task_list` | |
| **Forms** (3) | `create_google_form`, `read_google_form`, `read_form_responses` | |
| **Keep** (3) | `list_keep_notes`, `read_keep_note`, `create_keep_note` | |

## Setup

### 1. Google Cloud service account + domain-wide delegation

This server impersonates a real Workspace user through a service account:

1. Create a GCP project and enable the APIs you need: Calendar, Gmail, Drive, Docs, Sheets, Slides, Tasks, Forms, Keep.
2. Create a **service account** and enable **domain-wide delegation** on it (copy its Client ID).
3. In [Google Workspace Admin](https://admin.google.com) → *Security → Access and data control → API controls → Domain-wide delegation*, authorize the Client ID with these scopes:

   ```
   https://www.googleapis.com/auth/calendar
   https://www.googleapis.com/auth/calendar.events
   https://www.googleapis.com/auth/gmail.modify
   https://www.googleapis.com/auth/gmail.send
   https://www.googleapis.com/auth/drive
   https://www.googleapis.com/auth/documents
   https://www.googleapis.com/auth/spreadsheets
   https://www.googleapis.com/auth/presentations
   https://www.googleapis.com/auth/forms.body
   https://www.googleapis.com/auth/keep
   https://www.googleapis.com/auth/tasks
   ```

4. Download the service account's JSON key.

> **Note:** this auth model requires Google Workspace with admin access (domain-wide delegation). It does not work with consumer @gmail.com accounts.

### 2. Install

```bash
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
```

### 3. Configure environment

| Variable | Required | Description |
|---|---|---|
| `GOOGLE_APPLICATION_CREDENTIALS` | yes* | Path to the service account key JSON. Defaults to `./service_account.json` in the repo. |
| `WORKSPACE_USER_EMAIL` | yes | The Workspace user to impersonate (e.g. `you@yourdomain.com`). |

Verify everything works:

```bash
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service_account.json
export WORKSPACE_USER_EMAIL=you@yourdomain.com
.venv/bin/python verify_access.py
```

### 4. Wire up your MCP client

```json
{
  "mcpServers": {
    "google-workspace": {
      "command": "/path/to/google-workspace-mcp/.venv/bin/python",
      "args": ["/path/to/google-workspace-mcp/workspace_mcp_server.py"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service_account.json",
        "WORKSPACE_USER_EMAIL": "you@yourdomain.com"
      }
    }
  }
}
```

## Testing tools without a client

`mcp_cli.py` calls any tool over real MCP JSON-RPC:

```bash
.venv/bin/python mcp_cli.py list_calendars
.venv/bin/python mcp_cli.py upload_drive_file '{"file_name": "logo.psd", "local_path": "/tmp/logo.psd", "mime_type": "image/vnd.adobe.photoshop"}'
```

## Tests

```bash
.venv/bin/pytest tests/ -v
```

`test_workspace_access.py` makes live API calls and is skipped unless `WORKSPACE_USER_EMAIL` and a key file are configured.

## Requirements

Python 3.10+. Deps: `fastmcp`, `google-api-python-client`, `google-auth`, `google-auth-httplib2`, `google-auth-oauthlib` (see `requirements.txt`).

## License

MIT — see [LICENSE](LICENSE).