Google Services MCP
# Google Services MCP
A permission-controlled [Model Context Protocol](https://modelcontextprotocol.io) gateway that gives AI agents scoped,
auditable access to **Google Drive, Sheets, Gmail, Calendar and Docs** — with OAuth scopes, a server-side permission
policy, mandatory confirmation for destructive actions, rate limiting and a JSONL audit trail.
The design goal is blunt: an agent should be able to *read* your workspace by default, and only *change* it when a human
operator deliberately widened the policy. The policy lives in the server, not in the prompt, so no amount of prompting
can talk its way past it.
```
agent ──MCP──▶ tool wrapper ──▶ 1. rate limit ──▶ 2. permission policy ──▶ 3. Google API
│ │
└── 4. redact + truncate ◀────────────────┘
│
└──▶ audit.jsonl
```
## Highlights
- **Default read-only.** `read_only` mode blocks every write/destructive tool before a network call is made.
- **Per-service, per-action flags.** `drive.share`, `gmail.send`, `calendar.delete`, … each have their own switch.
- **Two-key outbound email.** Sending requires `permissions.allow_email_send: true` *and* `gmail.send: true` *and*
`confirm: true` on the call itself.
- **Dry-run by default.** Writes preview their effect unless the caller passes `dry_run: false`; deletions need
`confirm: true` as well.
- **44 tools** across five services, each with an MCP `ToolSpec` (operation, policy key, scopes, annotations).
- **Untrusted content handling.** Gmail/Drive/Docs text is wrapped and control characters stripped before it reaches the
model, so a malicious document cannot smuggle instructions.
- **Local file sandbox.** Drive upload/download are confined to `files.download_dir`; path traversal is rejected.
- **Audit without payloads.** `logs/audit.jsonl` records tool, service, outcome, duration, correlation id — never
message bodies or tokens.
## Install
```bash
git clone https://github.com/hamids-ai-automations/google-services-mcp.git
cd google-services-mcp
python -m venv .venv
.\.venv\Scripts\activate # Windows
# source .venv/bin/activate # macOS / Linux
pip install -e ".[dev]"
```
Requirements: Python 3.11+, an OAuth client (Desktop app) from Google Cloud Console with the Drive, Sheets, Gmail,
Calendar and Docs APIs enabled.
## Configure
```bash
cp config/config.example.yaml config/config.yaml
cp .env.example .env
```
Every flag in `permissions.services` maps to a policy key used by the tools. Widening one widens what the agent can do:
| Service | Policy keys | Notes |
| --- | --- | --- |
| `drive` | `read`, `create`, `update`, `upload`, `share`, `delete` | `delete` also needs `confirm=true` per call |
| `sheets` | `read`, `write`, `create`, `delete` | `delete` removes a whole sheet (irreversible) |
| `gmail` | `read`, `draft`, `send`, `modify`, `trash` | `send` needs `allow_email_send` + `confirm=true` |
| `calendar` | `read`, `create`, `update`, `delete` | deleting an event also needs `confirm=true` |
| `docs` | `read`, `create`, `update` | updates are append/insert/replace-text only |
`permissions.mode` adds a global gate on top: `read_only` (reads only), `read_write` (flag-driven), `restricted`
(only names in `allowed_tools`), `custom` (flags only, no mode-level short-circuit).
## Authorise
```bash
google-services-mcp auth login # opens a browser, stores the refresh token
google-services-mcp auth login --console # headless: paste the code
google-services-mcp auth login --write # request write scopes too
google-services-mcp auth status # token presence, expiry, granted scopes
google-services-mcp auth logout # revoke at Google and delete locally
```
Tick the scopes you actually intend to use. A token that was granted read-only scopes cannot perform writes even if the
policy allows them — the server fails fast with `INSUFFICIENT_SCOPES` instead of a confusing 403.
## Run
```bash
google-services-mcp serve # stdio (Claude Desktop, Cursor, Marvis, …)
GSMCP_TRANSPORT=streamable-http google-services-mcp serve
```
Register with an MCP client (stdio):
```json
{
"mcpServers": {
"google-services": {
"command": "D:\\GitHub Profile\\google-services-mcp\\.venv\\Scripts\\python.exe",
"args": ["-m", "google_services_mcp", "serve", "--config", "D:\\GitHub Profile\\google-services-mcp\\config\\config.yaml"]
}
}
}
```
`streamable-http` binds to loopback by default. Do **not** expose it directly: it has no built-in user authentication —
put an authenticating reverse proxy in front of it, or keep the transport on `stdio`.
## CLI
| Command | Purpose |
| --- | --- |
| `serve` | Run the MCP server over the configured transport. |
| `auth login / status / logout` | Manage the OAuth credential (never prints tokens). |
| `policy` | Print the effective permission matrix. |
| `doctor` | Config, credential, path and tool-allow-list diagnostics as JSON. |
## Tools
44 tools, all prefixed by service. See [docs/tools.md](docs/tools.md) for the full reference with policy keys and
arguments.
- **Drive** — `drive_search_files`, `drive_list_files`, `drive_get_file`, `drive_read_file`, `drive_download_file`,
`drive_upload_file`, `drive_create_folder`, `drive_copy_file`, `drive_move_file`, `drive_rename_file`,
`drive_share_file`, `drive_trash_file`, `drive_delete_file`, `drive_list_permissions`
- **Sheets** — `sheets_get_spreadsheet`, `sheets_read_range`, `sheets_batch_read`, `sheets_update_range`,
`sheets_append_rows`, `sheets_clear_range`, `sheets_create_spreadsheet`, `sheets_add_sheet`, `sheets_delete_sheet`
- **Gmail** — `gmail_get_profile`, `gmail_list_labels`, `gmail_search_messages`, `gmail_get_message`,
`gmail_list_threads`, `gmail_create_draft`, `gmail_send_email`, `gmail_modify_labels`, `gmail_trash_message`
- **Calendar** — `calendar_list_calendars`, `calendar_list_events`, `calendar_get_event`,
`calendar_check_availability`, `calendar_create_event`, `calendar_update_event`, `calendar_delete_event`
- **Docs** — `docs_get_document`, `docs_create_document`, `docs_append_text`, `docs_insert_text`, `docs_replace_text`
## Security model
Read [docs/security.md](docs/security.md) and [SECURITY.md](SECURITY.md). Short version:
1. Tools are only reachable if registered, and each registration carries an explicit `ToolSpec`.
2. `PermissionPolicy.check()` runs inside the wrapper before any HTTP call; denial is audited as `denied`.
3. Scopes are validated per service; missing scopes raise `INSUFFICIENT_SCOPES` with the missing list.
4. Destructive tools require `confirm: true`; writes default to `dry_run: true`.
5. Returned Google content is treated as data: wrapped, control-stripped, truncated, never executed.
## Development
```bash
.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m ruff check .
.\.venv\Scripts\python.exe -m ruff format --check .
.\.venv\Scripts\python.exe -m google_services_mcp --config config\config.example.yaml policy
.\.venv\Scripts\python.exe scripts\gen_tools_doc.py # regenerate docs/tools.md from ToolSpec metadata
```
CI (`.github/workflows/ci.yml`) runs the same commands on Ubuntu and Windows for Python 3.11 and 3.12, and fails if
`docs/tools.md` is out of date.
When adding a tool: declare a `ToolSpec`, register it in the service module, add a permission flag in `config.py` if it
introduces a new operation, then rerun `scripts/gen_tools_doc.py`.
Layout:
```
google_services_mcp/
config.py settings models + YAML/env loading
permissions.py policy + ToolSpec
tools/ one module per service + registry/wrapper
services/ typed Google API adapters
oauth/ token manager, scopes, authorisation flows
audit.py JSONL audit log with rotation
security.py redaction, truncation, sandboxing, untrusted wrapping
```
## License
MIT — see [LICENSE](LICENSE).
TDQS
Scored across 44 tools
Within each service, tools mostly target distinct action/resource pairs, with clear separation between read, write, trash, and delete operations. A few read-only discovery tools overlap slightly (drive_list_files vs drive_search_files, sheets_read_range vs sheets_batch_read, gmail_list_threads vs gmail_search_messages), but descriptions help disambiguate.
Every tool follows a predictable snake_case pattern with a service prefix and verb/action phrase (calendar_, docs_, drive_, sheets_, gmail_). There are no mixed conventions or vague names, making the set highly predictable.
44 tools for a single MCP server is well beyond the typical well-scoped 3-15 range and exceeds the 25+ threshold for being too many. Although they are grouped by Google service, this surface is likely better split into per-service servers for reliable agent selection.
Core lifecycle coverage is strong across services: Calendar has full CRUD, Drive has read/write/trash/share, Sheets has range and tab operations, Gmail has search/draft/send/label operations, and Docs has create/read/edit. Gaps remain in Drive permission revocation/update, Gmail label creation/deletion and thread retrieval, and some Docs/Sheets lifecycle operations, but most core workflows are covered.