Skip to content
Back to search

google-services-mcp

MCP server for Google Drive, Sheets, Gmail, Calendar and Docs - 44 tools, read-only by default, OAuth, permission gating, audit logging.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hamids-ai-automations--google-services-mcp/badge.svg)](/listings/hamids-ai-automations--google-services-mcp)

HTML

<a href="/listings/hamids-ai-automations--google-services-mcp"><img src="/api/listings/hamids-ai-automations--google-services-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 189 lines
  1. # Google Services MCP
  2. A permission-controlled [Model Context Protocol](https://modelcontextprotocol.io) gateway that gives AI agents scoped,
  3. auditable access to **Google Drive, Sheets, Gmail, Calendar and Docs** — with OAuth scopes, a server-side permission
  4. policy, mandatory confirmation for destructive actions, rate limiting and a JSONL audit trail.
  5. The design goal is blunt: an agent should be able to *read* your workspace by default, and only *change* it when a human
  6. operator deliberately widened the policy. The policy lives in the server, not in the prompt, so no amount of prompting
  7. can talk its way past it.
  8. ```
  9. agent ──MCP──▶ tool wrapper ──▶ 1. rate limit ──▶ 2. permission policy ──▶ 3. Google API
  10. │ │
  11. └── 4. redact + truncate ◀────────────────┘
  12. │
  13. └──▶ audit.jsonl
  14. ```
  15. ## Highlights
  16. - **Default read-only.** `read_only` mode blocks every write/destructive tool before a network call is made.
  17. - **Per-service, per-action flags.** `drive.share`, `gmail.send`, `calendar.delete`, … each have their own switch.
  18. - **Two-key outbound email.** Sending requires `permissions.allow_email_send: true` *and* `gmail.send: true` *and*
  19. `confirm: true` on the call itself.
  20. - **Dry-run by default.** Writes preview their effect unless the caller passes `dry_run: false`; deletions need
  21. `confirm: true` as well.
  22. - **44 tools** across five services, each with an MCP `ToolSpec` (operation, policy key, scopes, annotations).
  23. - **Untrusted content handling.** Gmail/Drive/Docs text is wrapped and control characters stripped before it reaches the
  24. model, so a malicious document cannot smuggle instructions.
  25. - **Local file sandbox.** Drive upload/download are confined to `files.download_dir`; path traversal is rejected.
  26. - **Audit without payloads.** `logs/audit.jsonl` records tool, service, outcome, duration, correlation id — never
  27. message bodies or tokens.
  28. ## Install
  29. ```bash
  30. git clone https://github.com/hamids-ai-automations/google-services-mcp.git
  31. cd google-services-mcp
  32. python -m venv .venv
  33. .\.venv\Scripts\activate # Windows
  34. # source .venv/bin/activate # macOS / Linux
  35. pip install -e ".[dev]"
  36. ```
  37. Requirements: Python 3.11+, an OAuth client (Desktop app) from Google Cloud Console with the Drive, Sheets, Gmail,
  38. Calendar and Docs APIs enabled.
  39. ## Configure
  40. ```bash
  41. cp config/config.example.yaml config/config.yaml
  42. cp .env.example .env
  43. ```
  44. Every flag in `permissions.services` maps to a policy key used by the tools. Widening one widens what the agent can do:
  45. | Service | Policy keys | Notes |
  46. | --- | --- | --- |
  47. | `drive` | `read`, `create`, `update`, `upload`, `share`, `delete` | `delete` also needs `confirm=true` per call |
  48. | `sheets` | `read`, `write`, `create`, `delete` | `delete` removes a whole sheet (irreversible) |
  49. | `gmail` | `read`, `draft`, `send`, `modify`, `trash` | `send` needs `allow_email_send` + `confirm=true` |
  50. | `calendar` | `read`, `create`, `update`, `delete` | deleting an event also needs `confirm=true` |
  51. | `docs` | `read`, `create`, `update` | updates are append/insert/replace-text only |
  52. `permissions.mode` adds a global gate on top: `read_only` (reads only), `read_write` (flag-driven), `restricted`
  53. (only names in `allowed_tools`), `custom` (flags only, no mode-level short-circuit).
  54. ## Authorise
  55. ```bash
  56. google-services-mcp auth login # opens a browser, stores the refresh token
  57. google-services-mcp auth login --console # headless: paste the code
  58. google-services-mcp auth login --write # request write scopes too
  59. google-services-mcp auth status # token presence, expiry, granted scopes
  60. google-services-mcp auth logout # revoke at Google and delete locally
  61. ```
  62. Tick the scopes you actually intend to use. A token that was granted read-only scopes cannot perform writes even if the
  63. policy allows them — the server fails fast with `INSUFFICIENT_SCOPES` instead of a confusing 403.
  64. ## Run
  65. ```bash
  66. google-services-mcp serve # stdio (Claude Desktop, Cursor, Marvis, …)
  67. GSMCP_TRANSPORT=streamable-http google-services-mcp serve
  68. ```
  69. Register with an MCP client (stdio):
  70. ```json
  71. {
  72. "mcpServers": {
  73. "google-services": {
  74. "command": "D:\\GitHub Profile\\google-services-mcp\\.venv\\Scripts\\python.exe",
  75. "args": ["-m", "google_services_mcp", "serve", "--config", "D:\\GitHub Profile\\google-services-mcp\\config\\config.yaml"]
  76. }
  77. }
  78. }
  79. ```
  80. `streamable-http` binds to loopback by default. Do **not** expose it directly: it has no built-in user authentication —
  81. put an authenticating reverse proxy in front of it, or keep the transport on `stdio`.
  82. ## CLI
  83. | Command | Purpose |
  84. | --- | --- |
  85. | `serve` | Run the MCP server over the configured transport. |
  86. | `auth login / status / logout` | Manage the OAuth credential (never prints tokens). |
  87. | `policy` | Print the effective permission matrix. |
  88. | `doctor` | Config, credential, path and tool-allow-list diagnostics as JSON. |
  89. ## Tools
  90. 44 tools, all prefixed by service. See [docs/tools.md](docs/tools.md) for the full reference with policy keys and
  91. arguments.
  92. - **Drive** — `drive_search_files`, `drive_list_files`, `drive_get_file`, `drive_read_file`, `drive_download_file`,
  93. `drive_upload_file`, `drive_create_folder`, `drive_copy_file`, `drive_move_file`, `drive_rename_file`,
  94. `drive_share_file`, `drive_trash_file`, `drive_delete_file`, `drive_list_permissions`
  95. - **Sheets** — `sheets_get_spreadsheet`, `sheets_read_range`, `sheets_batch_read`, `sheets_update_range`,
  96. `sheets_append_rows`, `sheets_clear_range`, `sheets_create_spreadsheet`, `sheets_add_sheet`, `sheets_delete_sheet`
  97. - **Gmail** — `gmail_get_profile`, `gmail_list_labels`, `gmail_search_messages`, `gmail_get_message`,
  98. `gmail_list_threads`, `gmail_create_draft`, `gmail_send_email`, `gmail_modify_labels`, `gmail_trash_message`
  99. - **Calendar** — `calendar_list_calendars`, `calendar_list_events`, `calendar_get_event`,
  100. `calendar_check_availability`, `calendar_create_event`, `calendar_update_event`, `calendar_delete_event`
  101. - **Docs** — `docs_get_document`, `docs_create_document`, `docs_append_text`, `docs_insert_text`, `docs_replace_text`
  102. ## Security model
  103. Read [docs/security.md](docs/security.md) and [SECURITY.md](SECURITY.md). Short version:
  104. 1. Tools are only reachable if registered, and each registration carries an explicit `ToolSpec`.
  105. 2. `PermissionPolicy.check()` runs inside the wrapper before any HTTP call; denial is audited as `denied`.
  106. 3. Scopes are validated per service; missing scopes raise `INSUFFICIENT_SCOPES` with the missing list.
  107. 4. Destructive tools require `confirm: true`; writes default to `dry_run: true`.
  108. 5. Returned Google content is treated as data: wrapped, control-stripped, truncated, never executed.
  109. ## Retry and rate-limit behaviour
  110. Every Google API call goes through `google_services_mcp.retry.execute_with_retry`:
  111. - **What is retried.** Only `429`, `500`, `502`, `503`, `504` (and transport errors with no HTTP status) are retried,
  112. and only for idempotent operations. Non-idempotent calls (`gmail_send_message`, event creation without a stable id)
  113. fail fast — a duplicate side effect is worse than a visible error.
  114. - **How long we wait.** When Google sends `Retry-After`, it is honoured in **both** RFC 9110 forms: `delay-seconds`
  115. (`Retry-After: 7`) and `HTTP-date` (`Retry-After: Sat, 21 Nov 2026 12:00:30 GMT`). Anything above
  116. `RETRY_AFTER_CEILING` (120 s) is clamped and logged as `retry_after_clamped`, because a single MCP tool call must not
  117. block for minutes. Without a hint, back-off is exponential from `backoff_base_seconds` with ±25 % jitter, capped at
  118. `backoff_max_seconds`.
  119. - **How many attempts.** `max_retries` (default 3) plus the initial attempt; the last failure surfaces as a typed
  120. `GoogleServicesMCPError` whose `retryable` flag tells the client whether a retry is worth trying.
  121. ```bash
  122. .\.venv\Scripts\python.exe -m pytest tests\test_retry.py -q # 15 cases, no network, no real sleeping
  123. ```
  124. ## Development
  125. ```bash
  126. .\.venv\Scripts\python.exe -m pytest -q
  127. .\.venv\Scripts\python.exe -m ruff check .
  128. .\.venv\Scripts\python.exe -m ruff format --check .
  129. .\.venv\Scripts\python.exe -m google_services_mcp --config config\config.example.yaml policy
  130. .\.venv\Scripts\python.exe scripts\gen_tools_doc.py # regenerate docs/tools.md from ToolSpec metadata
  131. ```
  132. CI (`.github/workflows/ci.yml`) runs the same commands on Ubuntu and Windows for Python 3.11 and 3.12, and fails if
  133. `docs/tools.md` is out of date.
  134. When adding a tool: declare a `ToolSpec`, register it in the service module, add a permission flag in `config.py` if it
  135. introduces a new operation, then rerun `scripts/gen_tools_doc.py`.
  136. Layout:
  137. ```
  138. google_services_mcp/
  139. config.py settings models + YAML/env loading
  140. permissions.py policy + ToolSpec
  141. tools/ one module per service + registry/wrapper
  142. services/ typed Google API adapters
  143. oauth/ token manager, scopes, authorisation flows
  144. audit.py JSONL audit log with rotation
  145. security.py redaction, truncation, sandboxing, untrusted wrapping
  146. ```
  147. ## License
  148. MIT — see [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.