Google Services MCP
Provides tools for Gmail access and management: searching and reading messages and threads, listing labels, creating drafts, sending email when explicitly permitted and confirmed, modifying labels, and trashing messages.
Provides tools for Google Drive file and folder management: searching, listing, reading, downloading, uploading, creating folders, copying, moving, renaming, sharing, trashing/deleting files, and listing permissions, with policy-gated writes and dry-run previews.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Google Services MCP What are the last five unread emails from my boss?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.jsonlHighlights
Default read-only.
read_onlymode 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: trueandgmail.send: trueandconfirm: trueon the call itself.Dry-run by default. Writes preview their effect unless the caller passes
dry_run: false; deletions needconfirm: trueas 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.jsonlrecords 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 .envEvery 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 |
|
|
|
|
|
|
|
|
|
|
| deleting an event also needs |
|
| 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 locallyTick 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 serveRegister 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 |
| Run the MCP server over the configured transport. |
| Manage the OAuth credential (never prints tokens). |
| Print the effective permission matrix. |
| 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_permissionsSheets —
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_sheetGmail —
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_messageCalendar —
calendar_list_calendars,calendar_list_events,calendar_get_event,calendar_check_availability,calendar_create_event,calendar_update_event,calendar_delete_eventDocs —
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:
Tools are only reachable if registered, and each registration carries an explicit
ToolSpec.PermissionPolicy.check()runs inside the wrapper before any HTTP call; denial is audited asdenied.Scopes are validated per service; missing scopes raise
INSUFFICIENT_SCOPESwith the missing list.Destructive tools require
confirm: true; writes default todry_run: true.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 metadataCI (.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 wrappingLicense
MIT — see LICENSE.
Available Tools
44 toolscalendar_check_availabilitycalendar check availabilityCRead-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 eventCDestructiveIdempotent
Delete a calendar event. Requires confirm=true.
Inputs: event_id (required), confirm, calendar_id, send_updates. Returns: object
calendar_get_eventcalendar get eventCRead-onlyIdempotent
Fetch a single calendar event by ID.
Inputs: event_id (required), calendar_id. Returns: object
calendar_list_calendarscalendar list calendarsARead-onlyIdempotent
List calendars visible to the connected account with access roles.
Inputs: no named parameters. Returns: object
calendar_list_eventscalendar list eventsBRead-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 eventBIdempotent
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 documentBRead-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 textBIdempotent
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 fileADestructiveIdempotent
Permanently delete a Drive file. Requires confirm=true; irreversible.
Inputs: file_id (required), confirm. Returns: object
drive_download_filedrive download fileBRead-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 fileBRead-onlyIdempotent
Fetch metadata for a single Drive file, including owners, size and web link.
Inputs: file_id (required). Returns: object
drive_list_filesdrive list filesCRead-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 permissionsBRead-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 fileBRead-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 fileCIdempotent
Rename a Drive file.
Inputs: file_id (required), new_name (required). Returns: object
drive_search_filesdrive search filesBRead-onlyIdempotent
Search Drive by file name or full text. Read-only; returns metadata only.
Inputs: query (required), page_size. Returns: object
drive_trash_filedrive trash fileADestructiveIdempotent
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 messageBRead-onlyIdempotent
Fetch one message with headers and a truncated plain-text body.
Inputs: message_id (required), body_chars. Returns: object
gmail_get_profilegmail get profileARead-onlyIdempotent
Get the connected Gmail address and mailbox totals.
Inputs: no named parameters. Returns: object
gmail_list_labelsgmail list labelsARead-onlyIdempotent
List Gmail labels (including system labels such as INBOX and UNREAD).
Inputs: no named parameters. Returns: object
gmail_list_threadsgmail list threadsCRead-onlyIdempotent
List Gmail threads matching an optional query.
Inputs: query, max_results. Returns: object
gmail_modify_labelsgmail modify labelsBIdempotent
Add or remove labels on a message (e.g. mark read, archive).
Inputs: message_id (required), add, remove. Returns: object
gmail_search_messagesgmail search messagesARead-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 messageBDestructiveIdempotent
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 readBRead-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 rangeBDestructiveIdempotent
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 sheetADestructiveIdempotent
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 spreadsheetARead-onlyIdempotent
Get spreadsheet metadata: title, locale, time zone and the list of tabs.
Inputs: spreadsheet_id (required). Returns: object
sheets_read_rangesheets read rangeCRead-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 rangeBIdempotent
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
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.
Maintenance
Related MCP Connectors
Multiple Gmail accounts, editable Google Sheets & Docs for AI agents. Deny-by-default access rules.
Gmail, Outlook, Drive, OneDrive and calendars for AI agents. Many accounts, one endpoint, audit log.
Permissioned access to Gmail, Drive and Calendar via the user's own Google account
Connect assistants to your company tools with per-person, per-action grants and a full audit log.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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-
- AlicenseNot gradedqualityCmaintenanceEnables 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
- AlicenseNot gradedqualityBmaintenanceEnables 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.2MIT
- FlicenseNot gradedqualityBmaintenanceEnables 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.-