Skip to main content
Glama

Google Services MCP

A permission-controlled Model Context Protocol 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.

Related MCP server: Krakenfy Drive MCP

Install

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

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

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

google-services-mcp serve                        # stdio (Claude Desktop, Cursor, Marvis, …)
GSMCP_TRANSPORT=streamable-http google-services-mcp serve

Register with an MCP client (stdio):

{
  "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 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 and 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

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

Available Tools

44 tools
calendar_check_availabilitycalendar check availabilityC
Read-onlyIdempotent

Query free/busy blocks for one or more calendars in a time window.

Inputs: time_max (required), time_min (required), time_zone, calendar_ids. Returns: object

calendar_create_eventcalendar create eventB

Create an event. Supports dry_run=true to preview the payload without writing.

Inputs: end (required), start (required), summary (required), dry_run, +6 more. Returns: object

calendar_delete_eventcalendar delete eventC
DestructiveIdempotent

Delete a calendar event. Requires confirm=true.

Inputs: event_id (required), confirm, calendar_id, send_updates. Returns: object

calendar_get_eventcalendar get eventC
Read-onlyIdempotent

Fetch a single calendar event by ID.

Inputs: event_id (required), calendar_id. Returns: object

calendar_list_calendarscalendar list calendarsA
Read-onlyIdempotent

List calendars visible to the connected account with access roles.

Inputs: no named parameters. Returns: object

calendar_list_eventscalendar list eventsB
Read-onlyIdempotent

List events in a time window (RFC3339), optionally filtered by free-text query.

Inputs: query, time_max, time_min, calendar_id, +1 more. Returns: object

calendar_update_eventcalendar update eventB
Idempotent

Patch fields on an existing event (summary, times, location, attendees).

Inputs: event_id (required), end, start, summary, +6 more. Returns: object

docs_append_textdocs append textB

Append text to the end of a document, optionally as a named heading style.

Inputs: text (required), document_id (required), heading_style. Returns: object

docs_create_documentdocs create documentC

Create a Google Doc with optional initial text. Write operation.

Inputs: title (required), initial_text. Returns: object

docs_get_documentdocs get documentB
Read-onlyIdempotent

Read a Google Doc: title, headings, table count and plain-text body (truncated).

Inputs: document_id (required), max_chars. Returns: object

docs_insert_textdocs insert textC

Insert text at a specific document index.

Inputs: text (required), index (required), document_id (required). Returns: object

docs_replace_textdocs replace textB
Idempotent

Replace all occurrences of a string in a document; reports how many changed.

Inputs: find (required), replace (required), document_id (required), match_case. Returns: object

drive_copy_filedrive copy fileB

Copy a Drive file, optionally into another folder. Write operation.

Inputs: file_id (required), name, parent_id. Returns: object

drive_create_folderdrive create folderC

Create a Drive folder. Write operation; audited.

Inputs: name (required), parent_id. Returns: object

drive_delete_filedrive delete fileA
DestructiveIdempotent

Permanently delete a Drive file. Requires confirm=true; irreversible.

Inputs: file_id (required), confirm. Returns: object

drive_download_filedrive download fileB
Read-onlyIdempotent

Download a Drive file into the server's download directory (path-traversal guarded).

Inputs: file_id (required), destination (required). Returns: object

drive_get_filedrive get fileB
Read-onlyIdempotent

Fetch metadata for a single Drive file, including owners, size and web link.

Inputs: file_id (required). Returns: object

drive_list_filesdrive list filesC
Read-onlyIdempotent

List Drive files with an optional raw Drive query (e.g. "mimeType='application/pdf'"). Read-only.

Inputs: query, order_by, page_size, page_token, +1 more. Returns: object

drive_list_permissionsdrive list permissionsB
Read-onlyIdempotent

List the permissions currently set on a Drive file.

Inputs: file_id (required). Returns: object

drive_move_filedrive move fileB

Move a Drive file to a new parent folder. Metadata-only change.

Inputs: file_id (required), add_parent (required), remove_parent. Returns: object

drive_read_filedrive read fileB
Read-onlyIdempotent

Read a Drive file's text content. Google-native files are exported to text; size-capped.

Inputs: file_id (required), max_bytes. Returns: object

drive_rename_filedrive rename fileC
Idempotent

Rename a Drive file.

Inputs: file_id (required), new_name (required). Returns: object

drive_search_filesdrive search filesB
Read-onlyIdempotent

Search Drive by file name or full text. Read-only; returns metadata only.

Inputs: query (required), page_size. Returns: object

drive_share_filedrive share fileB

Grant a user or domain access to a Drive file. Access-control change; audited.

Inputs: file_id (required), role, email, domain, +1 more. Returns: object

drive_trash_filedrive trash fileA
DestructiveIdempotent

Move a Drive file to trash (recoverable for 30 days). Destructive.

Inputs: file_id (required). Returns: object

drive_upload_filedrive upload fileB

Upload a local file from the server's download directory into Drive. Write operation.

Inputs: local_path (required), name, mime_type, parent_id. Returns: object

gmail_create_draftgmail create draftB

Create a Gmail draft. Preferred over sending: nothing leaves the mailbox.

Inputs: to (required), body (required), subject (required), cc, +3 more. Returns: object

gmail_get_messagegmail get messageB
Read-onlyIdempotent

Fetch one message with headers and a truncated plain-text body.

Inputs: message_id (required), body_chars. Returns: object

gmail_get_profilegmail get profileA
Read-onlyIdempotent

Get the connected Gmail address and mailbox totals.

Inputs: no named parameters. Returns: object

gmail_list_labelsgmail list labelsA
Read-onlyIdempotent

List Gmail labels (including system labels such as INBOX and UNREAD).

Inputs: no named parameters. Returns: object

gmail_list_threadsgmail list threadsC
Read-onlyIdempotent

List Gmail threads matching an optional query.

Inputs: query, max_results. Returns: object

gmail_modify_labelsgmail modify labelsB
Idempotent

Add or remove labels on a message (e.g. mark read, archive).

Inputs: message_id (required), add, remove. Returns: object

gmail_search_messagesgmail search messagesA
Read-onlyIdempotent

Search Gmail with Gmail query syntax (e.g. 'from:boss@x.com is:unread newer_than:7d'). Returns message IDs.

Inputs: query (required), label_ids, max_results, include_spam_trash. Returns: object

gmail_send_emailgmail send emailA

Send an email. Requires confirm=true and allow_email_send=true; returns a dry-run preview otherwise.

Inputs: to (required), body (required), subject (required), cc, +4 more. Returns: object

gmail_trash_messagegmail trash messageB
DestructiveIdempotent

Move a message to Gmail trash (recoverable).

Inputs: message_id (required). Returns: object

sheets_add_sheetsheets add sheetC

Add a new tab to an existing spreadsheet.

Inputs: sheet_title (required), spreadsheet_id (required). Returns: object

sheets_append_rowssheets append rowsC

Append rows after the last row of a table. Write operation.

Inputs: values (required), range_a1 (required), spreadsheet_id (required), value_input. Returns: object

sheets_batch_readsheets batch readB
Read-onlyIdempotent

Read several A1 ranges from one spreadsheet in a single API call.

Inputs: ranges (required), spreadsheet_id (required), value_render. Returns: object

sheets_clear_rangesheets clear rangeB
DestructiveIdempotent

Clear values in an A1 range, keeping formatting. Destructive to cell data.

Inputs: range_a1 (required), spreadsheet_id (required). Returns: object

sheets_create_spreadsheetsheets create spreadsheetB

Create a new spreadsheet with an optional initial tab. Write operation.

Inputs: title (required), sheet_title. Returns: object

sheets_delete_sheetsheets delete sheetA
DestructiveIdempotent

Delete a tab (by numeric sheetId) from a spreadsheet. Requires confirm=true.

Inputs: sheet_id (required), spreadsheet_id (required), confirm. Returns: object

sheets_get_spreadsheetsheets get spreadsheetA
Read-onlyIdempotent

Get spreadsheet metadata: title, locale, time zone and the list of tabs.

Inputs: spreadsheet_id (required). Returns: object

sheets_read_rangesheets read rangeC
Read-onlyIdempotent

Read an A1 range (e.g. 'Sheet1!A1:D20') from a spreadsheet. Read-only.

Inputs: range_a1 (required), spreadsheet_id (required), value_render. Returns: object

sheets_update_rangesheets update rangeB
Idempotent

Overwrite an A1 range with a 2-D values array. Write operation; audited.

Inputs: values (required), range_a1 (required), spreadsheet_id (required), value_input. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 44 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables natural language control over Google Workspace (Gmail, Drive, Calendar, Sheets, Slides, Tasks) through secure OAuth 2.1 authentication, with vault-level security and multi-user isolation.
      7
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to automate Google Drive tasks such as provisioning workspaces, reusing templates, inspecting folder structures, updating reports, and sharing files through user-controlled OAuth.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables coding agents to read and manage Google Workspace apps like Gmail, Drive, Docs, Sheets, and Calendar through 41 tools, with staged writes that require review and explicit commit before any change is applied.
      2
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to securely access Gmail, Google Sheets, and Google Docs with fine-grained, deny-by-default permissions, including read/write restrictions, send whitelists, and one-click approvals.
      -