<div align="center">

# Google Workspace MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/downloads/)

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

</div>

---

## 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.

## Services

<table width="100%" align="center">
<tr>
<td align="center" width="25%">
<h3>📧</h3><b>Gmail</b><br>
<sub>15 tools - search, send, draft,<br>labels, filters, attachments</sub>
</td>
<td align="center" width="25%">
<h3>📁</h3><b>Drive</b><br>
<sub>16 tools - search, create, share,<br>import Office files</sub>
</td>
<td align="center" width="25%">
<h3>📅</h3><b>Calendar</b><br>
<sub>7 tools - events, free/busy,<br>Out of Office, Focus Time</sub>
</td>
<td align="center" width="25%">
<h3>📝</h3><b>Docs</b><br>
<sub>19 tools - edit, style, tables,<br>tabs, comments, export</sub>
</td>
</tr>
<tr>
<td align="center" width="25%">
<h3>📊</h3><b>Sheets</b><br>
<sub>14 tools - ranges, tables,<br>formatting, conditional rules</sub>
</td>
</tr>
</table>

## Quick Start

You'll need an OAuth client from [Google Cloud Console](https://console.cloud.google.com/) with the relevant APIs enabled (Gmail, Drive, Calendar, Docs, Sheets).

```bash
# 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:

```json
{
  "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:

```bash
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

```bash
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`](LICENSE).