gsuite-mcp
Provides tools for Gmail, including reading/searching messages, creating and sending messages/drafts with RFC 5322 reply threading, bulk exporting messages and attachments, and modifying labels. Write and send operations are gated by environment flags.
Provides tools for Google Calendar, including reading calendars/events and, when write is enabled, creating, updating, and deleting events.
Provides tools for Google Docs, including reading document structures and plain text, creating documents, inserting or replacing text, and applying advanced batch updates when writes are enabled.
Provides read-only tools for Google Drive, including browsing My Drive and shared-drive folders, searching with Drive query syntax, inspecting metadata, reading text content, and downloading/exporting files.
Provides tools for Google Sheets, including inspecting tabs and metadata, reading multiple cell ranges, creating spreadsheets, writing/appending/clearing values, and applying formatting or structural updates. Value writes default to RAW, with USER_ENTERED available.
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., "@gsuite-mcp summarize my unread emails from today"
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.
gsuite-mcp
MCP server for Gmail, Google Calendar, Google Docs, Google Sheets, and Google Drive. Supports multiple Google accounts. TypeScript, local stdio or authenticated Streamable HTTP over HTTPS.
Design
Writes are explicitly gated. OAuth grants write-capable scopes, but mutating tools are only registered when their environment flags are enabled:
GMAIL_ENABLE_WRITE,GMAIL_ENABLE_SEND,CALENDAR_ENABLE_WRITE,DOCS_ENABLE_WRITE, andSHEETS_ENABLE_WRITE. All default to disabled.Proper RFC 5322 reply threading. Pass
reply_to_message_idtogmail_create_draftorgmail_send_messageand the server fetches the source message, setsIn-Reply-To/References, and reusesthreadId.Bulk-first.
gmail_bulk_exportdumps a query result (metadata + bodies + attachments) to a directory;gmail_bulk_modify_labelscallsbatchModifyso 1000 messages cost one API call.Account-aware. Add accounts without restarting the server. Every Gmail, Calendar, Docs, Sheets, and Drive tool accepts
email; it is required when multiple accounts are configured and optional when there is only one.Google Docs read/write. Read complete document structures or plain text, create documents, insert/replace text, and apply advanced batch updates.
Google Sheets read/write. Inspect tabs and metadata, read multiple cell ranges, create spreadsheets, write or append values, clear cells, and apply formatting or structural updates. Value writes default to
RAW; chooseUSER_ENTEREDto interpret formulas and dates.Google Drive browsing. Browse My Drive and shared-drive folders, search with Drive query syntax, inspect metadata, read text content, and download/export files. Drive access is read-only.
Tokens stored under
~/.config/gmail-mcp/with0600. Refresh tokens are persisted on rotation. Override withGMAIL_MCP_CONFIG_DIR=/some/path.Remote credential isolation. Run HTTPS on a trusted host or dedicated container. Google tokens stay there; agent containers connect to
/mcpwith a separate MCP access key. Remote clients cannot authorize accounts or write server files.
Related MCP server: Multi-Account MCP
Install
npx -y gsuite-mcp@latestPrerequisites
A Google account. That's it — the package ships with a default OAuth client, so you do not need to create your own GCP project.
Optional: bring your own OAuth client
If you'd rather run against your own Google Cloud project (separate quota, your own consent screen):
Enable the Gmail API, Calendar API, Google Docs API, Google Sheets API, and Google Drive API on the project.
Configure the OAuth consent screen (External, Testing mode is fine — add yourself as a Test user).
Create an OAuth 2.0 Client ID of type Desktop app and download the credentials JSON.
Save it as
~/.config/gmail-mcp/oauth-client.json. When present, this file overrides the bundled defaults.
HTTPS: keep Google tokens outside agent containers
Run the MCP server as a separate service on a trusted host or in a dedicated container. Mount the Google configuration directory only into that service, with write access for refreshed tokens. Do not share its home directory, token directory, TLS private key, or container runtime socket with agents.
Authorize Google accounts on the trusted host using the local stdio setup below. Existing
token.jsonfiles work unchanged. For an existing installation, the defaultGMAIL_MCP_CONFIG_DIRis still~/.config/gmail-mcp.Generate a separate MCP access key once on that host:
umask 077 mkdir -p "$HOME/.config/gsuite-mcp-server" openssl rand -hex 32 > "$HOME/.config/gsuite-mcp-server/access-key"Build this checkout with
npm ci && npm run build, supply a TLS certificate/key for the hostname agents will use, and start the service:GSUITE_MCP_TRANSPORT=https \ GSUITE_MCP_HOST=0.0.0.0 \ GSUITE_MCP_PORT=8443 \ GSUITE_MCP_TLS_CERT_FILE=/etc/gsuite-mcp/fullchain.pem \ GSUITE_MCP_TLS_KEY_FILE=/etc/gsuite-mcp/privkey.pem \ GSUITE_MCP_BEARER_TOKEN_FILE="$HOME/.config/gsuite-mcp-server/access-key" \ GMAIL_MCP_CONFIG_DIR="$HOME/.config/gmail-mcp" \ node dist/src/index.jsThe certificate must be trusted by your MCP client and valid for its connection hostname. Use your internal CA or a publicly trusted certificate; keep certificate verification enabled. Set the existing write flags on this server process to enable mutating tools.
Configure the agent's MCP client for Streamable HTTP at
https://mcp.example.com:8443/mcp, withAuthorization: Bearer <MCP_ACCESS_KEY>. Use the hostname in your certificate. Clients that accept JSON HTTP configuration can use:{ "mcpServers": { "gmail": { "type": "http", "url": "https://mcp.example.com:8443/mcp", "headers": { "Authorization": "Bearer <MCP_ACCESS_KEY>" } } } }Prefer the client's secret/header injection mechanism over storing the key in a repository. Replace the previous
command/argsstdio entry; agents no longer launch this server or receive its Google credentials.
The MCP access key grants access to every configured Google account and every enabled remote tool on this server; it is not a Google access or refresh token. If no credentials at all may enter agent containers, have a trusted MCP client/gateway outside them inject the Authorization header. Rotate the MCP key independently of Google tokens and restart the service after rotation. This is a shared trusted service, not per-agent account authorization.
Remote mode exposes setup_list_accounts, but omits setup_auth, setup_add_account, drive_download_file, gmail_download_attachments, and gmail_bulk_export. Arbitrary output paths on the token-owning server would allow credential or code overwrites. Use remote read tools such as drive_read_file for returned content. These local file tools remain available over stdio. To add or reauthorize an account, stop the remote service, use a local stdio client on the trusted host with the same config directory, then restart the service. Avoid multiple processes writing the same token registry.
Docker on a private agent network
The Dockerfile serves plain HTTP with GSUITE_MCP_ALLOW_PRIVATE_HTTP=true, and every request still needs the bearer key. The gsuite-mcp service in ../browser-sandbox/docker-compose.yml runs it on the external mcp network. That service mounts ~/.config/gmail-mcp as the registry and reads its key from ~/.config/mcp-access-keys/gsuite. Agents use http://gsuite-mcp:8080/mcp with Authorization: Bearer <key>; the host uses http://127.0.0.1:8932/mcp. Do not mount ~/.config/gmail-mcp into agent containers. To add or reauthorize an account, run docker compose stop gsuite-mcp, use a local stdio client, then start the service again.
HTTPS at an existing reverse proxy
For a proxy on the same host/network namespace, use GSUITE_MCP_TRANSPORT=http with GSUITE_MCP_HOST=127.0.0.1 and GSUITE_MCP_PORT=8080, omit the TLS file settings, and keep the MCP access key configured. The HTTP backend refuses non-loopback binds. Publish only the proxy's HTTPS endpoint, preserving /mcp and the Authorization header. For example, a Caddy site can forward to the backend:
mcp.example.com {
reverse_proxy 127.0.0.1:8080
}A proxy in a separate network namespace must connect to the server's direct HTTPS listener instead. HTTP mode never trusts X-Forwarded-* headers to bypass authentication.
Transport settings
Environment variable | Default / meaning |
|
|
|
|
|
|
| Required PEM certificate/full chain for HTTPS |
| Required PEM private key for HTTPS |
| File containing the MCP access key (at least 32 characters) |
| Alternative to the token file; configure exactly one source |
| Optional comma-separated exact HTTPS origins; requests with an Origin header are otherwise rejected |
Native MCP clients normally omit Origin. The endpoint does not enable browser CORS. Following the MCP transport security requirements, it validates any supplied Origin and authenticates every request. /mcp uses stateless POST requests with JSON responses, supports concurrent clients, and limits request bodies to 4 MiB. GET/DELETE return 405; no persistent sessions or legacy SSE endpoint are created.
Register a local stdio client
For Claude Code, add to ~/.claude.json under mcpServers:
{
"mcpServers": {
"gmail": {
"command": "npx",
"args": ["-y", "gsuite-mcp@latest"],
"env": {}
}
}
}Enable only the write surfaces you want exposed:
"env": {
"GMAIL_ENABLE_WRITE": "true",
"GMAIL_ENABLE_SEND": "true",
"CALENDAR_ENABLE_WRITE": "true",
"DOCS_ENABLE_WRITE": "true",
"SHEETS_ENABLE_WRITE": "true"
}GMAIL_ENABLE_WRITE— label changes and draft create/update/deleteGMAIL_ENABLE_SEND— immediate message/draft sendingCALENDAR_ENABLE_WRITE— event create/update/deleteDOCS_ENABLE_WRITE— document create, insert/replace text, and advanced batch updatesSHEETS_ENABLE_WRITE— spreadsheet creation, value writes/appends/clears, and advanced formatting or structural updates
Restart the MCP server after changing environment flags so its tool list is rebuilt.
Authorize accounts (local stdio MCP)
On the trusted host, after the server is registered with a local stdio client:
Ask the model to call
setup_authwith no arguments (or with the intendedemail). It returns a URL.Open the URL in a browser, pick the account, grant access.
Your browser shows
ERR_CONNECTION_REFUSEDonhttp://localhost/?code=...— expected. Copy the full URL from the address bar.Ask the model to call
setup_authagain, passing the URL asurl_or_code. The token is saved; Gmail, Calendar, Docs, Sheets, and Drive tools become live without restart.
PKCE is used end-to-end. No loopback server is run.
To add another account, use setup_add_account with the same two-call flow. Use setup_list_accounts to see configured emails and granted scopes. Once two or more accounts are configured, pass email to every Gmail, Calendar, Docs, Sheets, and Drive tool call; calls without it return the list of available accounts and an error. Email matching is case-insensitive.
Existing installations should run setup_auth once again for each account to grant the Google Drive read-only scope (and the Google Docs scope if it was not granted previously). The old single-account token format is migrated automatically when the server can identify its account.
Adding Sheets to an existing installation
Build and restart the updated server. For a local checkout, run
npm installandnpm run build, and point the MCP client atnode /absolute/path/to/gsuite-mcp/dist/src/index.js.Existing
drive.readonlygrants already permit native Sheets reads. The Google Sheets API must also be enabled in the OAuth client's Google Cloud project.To edit, set
SHEETS_ENABLE_WRITE=truein the MCP server environment and restart it. Runsetup_authfor each account you want to edit with and complete Google's consent flow to granthttps://www.googleapis.com/auth/spreadsheets.Check
setup_list_accountsfor the granted Sheets scope. A newly requested scope does not upgrade existing tokens automatically, and the account still needs edit permission on each target spreadsheet.
See Google's read authorization scopes and Sheets scopes.
Tool surface
Setup (account authorization is local stdio only; listing is also available remotely)
setup_auth— authorize the first account or reauthorize an existing accountsetup_add_account— authorize another account without replacing existing accountssetup_list_accounts— list account emails and granted scopes
All Gmail, Calendar, Docs, Sheets, and Drive tools below accept an email parameter. It may be omitted only when exactly one account is configured.
Gmail (always on)
gmail_search— Gmail query syntax. Returns enriched metadata (from/subject/date/snippet/labelIds/hasAttachments) by default; passformat: 'ids'for ID-only.gmail_get_message,gmail_get_threadgmail_list_labelsgmail_list_drafts,gmail_get_draftgmail_download_attachments— bulk by query, with mime/filename filters (local stdio only)gmail_bulk_export— bulk export to per-message subdirectories (metadata, body, attachments) plus a top-levelindex.json(local stdio only)
Gmail (only when GMAIL_ENABLE_WRITE=true)
gmail_modify_labels,gmail_bulk_modify_labelsgmail_create_draft,gmail_update_draft,gmail_delete_draft
Gmail (only when GMAIL_ENABLE_SEND=true)
gmail_send_message,gmail_send_draft
Calendar (always on)
calendar_list_calendars,calendar_list_events,calendar_get_event
Calendar (only when CALENDAR_ENABLE_WRITE=true)
calendar_create_event,calendar_update_event,calendar_delete_event
Google Docs (always on)
docs_read_document— accept a document ID or Docs URL and return readable text per tab plus combined textdocs_get_document— return the full structured Google Docs API response
Google Docs (only when DOCS_ENABLE_WRITE=true)
docs_create_document— create a document with optional initial textdocs_insert_text— append or insert text at a Docs API indexdocs_replace_all_text— replace matching text across all or selected tabsdocs_batch_update— apply advanced Docs API edits and formatting requests
Google Sheets (always on)
sheets_get_spreadsheet— accept a spreadsheet ID or URL; return metadata, tab IDs/titles, grid dimensions, named ranges, and other properties. Setinclude_grid_data=truewithrangesto inspect cell formatting.sheets_read_values— read one or more A1 ranges across tabs; choose formatted values, calculated values, or formulas, and row or column orientation
Google Sheets (only when SHEETS_ENABLE_WRITE=true)
sheets_create_spreadsheet— create a spreadsheet with optional named tabs, locale, and time zone; returns its URL and tab IDssheets_write_values— write multiple ranges in one API call;RAWby default, orUSER_ENTEREDfor formulas and parsed inputsheets_append_values— append after the logical table found in an A1 range; inserts rows by default and returns the actual destination rangesheets_clear_values— clear values in multiple ranges while preserving formatting and validationsheets_batch_update— advanced Sheets API requests for tabs, rows/columns, formatting, filters, validation, charts, and other spreadsheet changes
Find spreadsheets with drive_search_files and query: "mimeType = 'application/vnd.google-apps.spreadsheet'". Use sheets_get_spreadsheet to discover tab titles and numeric IDs before reading or editing. A URL's gid is not used to select a tab: qualify ranges explicitly, such as 'Program budget'!A1:D20. For tabs with apostrophes, double the apostrophe, for example 'Team''s budget'!A1:D20.
Example sheets_write_values arguments:
{
"email": "you@example.com",
"spreadsheet_id_or_url": "YOUR_SPREADSHEET_ID",
"value_input_option": "USER_ENTERED",
"data": [
{ "range": "'Summary'!A1:B2", "values": [["Item", "Total"], ["Budget", "=SUM('Costs'!B2:B100)"]] }
]
}Cell values may be strings, numbers, booleans, or null. null skips a cell; "" clears it. Reads omit trailing empty rows and columns. Advanced batch requests use Google's camelCase request fields, numeric sheetId values, and zero-based grid indexes with exclusive end indexes. The value write tools use A1 ranges instead.
Google Drive (read-only)
drive_list_folder— list the direct children of My Drive root or a folder ID/URL, with pagination and optional filtersdrive_search_files— search files and folders with Google Drive API query syntaxdrive_get_file— return detailed metadata for a file, folder, or shortcutdrive_read_file— return text content; exports Docs/Sheets/Slides to text or CSV by defaultdrive_download_file— download a blob file or export a Google Workspace file to an absolute local path (local stdio only)drive_list_shared_drives— list shared drives accessible to the selected account
Scopes
https://www.googleapis.com/auth/gmail.modify(read, draft, label, send)https://www.googleapis.com/auth/calendarhttps://www.googleapis.com/auth/documentshttps://www.googleapis.com/auth/spreadsheetshttps://www.googleapis.com/auth/drive.readonly
Gmail has no scope that grants drafts without also granting send. Send is gated at the tool layer, not the scope layer — Google's own official MCP makes the same tradeoff.
Config paths
OAuth client (optional override):
~/.config/gmail-mcp/oauth-client.jsonAccount token registry:
~/.config/gmail-mcp/token.json
Override with GMAIL_MCP_CONFIG_DIR=/some/path.
License
MIT
Available Tools
24 toolscalendar_get_eventC
Fetch a single event.
Inputs: event_id (required), email, calendar_id.
calendar_list_calendarsC
List the user's calendars.
Inputs: email.
calendar_list_eventsC
List events on a calendar in a time window. Default calendar_id is 'primary'.
Inputs: email, query, time_max, time_min, +4 more.
docs_get_documentB
Fetch a Google Doc as the full structured Google Docs API document, including all document tabs by default.
Inputs: document_id_or_url (required), email, include_tabs_content.
docs_read_documentB
Read the text of a Google Doc. Returns plain text for each tab (including nested tabs), plus combined text and document metadata. Tables are rendered as tab-separated rows.
Inputs: document_id_or_url (required), email.
drive_download_fileA
Download a Drive file to an exact local path. Native Google Workspace files are exported (Docs as text, Sheets as CSV, Slides as text) unless export_mime_type is specified.
Inputs: dest_path (required), file_id_or_url (required), email, export_mime_type.
drive_get_fileB
Get detailed metadata for a Google Drive file, folder, or shortcut.
Inputs: file_id_or_url (required), email.
drive_list_folderA
List the direct children of a Google Drive folder, including folders, files, and shortcuts. Supports My Drive and shared drives. Omit folder_id_or_url to list My Drive's root.
Inputs: email, drive_id, order_by, page_size, +5 more.
drive_read_fileA
Read a text file from Google Drive. Native Docs, Sheets, and Slides are exported to plain text/CSV by default. Binary files should be saved with drive_download_file instead.
Inputs: file_id_or_url (required), email, max_characters, export_mime_type.
drive_search_filesA
Search Google Drive files and folders with Google Drive API query syntax (for example: name contains 'report', fullText contains 'quarterly', mimeType = 'application/pdf', or sharedWithMe). Includes My Drive and shared-drive items.
Inputs: query (required), email, corpora, drive_id, +4 more.
gmail_bulk_exportA
Bulk-export messages matching a Gmail search query to a directory. Per message: <dest_dir>//{message.json, body.txt, body.html, attachments/...}. Also writes <dest_dir>/index.json summarizing all exported messages.
Inputs: query (required), dest_dir (required), email, max_messages, +2 more.
gmail_download_attachmentsB
Download attachments from messages matching a Gmail search query into a destination directory. Files are named <messageId>__<originalFilename> to avoid collisions. Returns a summary.
Inputs: query (required), dest_dir (required), email, max_messages, +2 more.
gmail_get_draftC
Fetch a draft's full content.
Inputs: id (required), email.
gmail_get_messageA
Fetch a single Gmail message by ID with headers and decoded text body.
Inputs: id (required), email, format.
gmail_get_threadB
Fetch an entire Gmail thread by ID with all messages in order.
Inputs: id (required), email.
gmail_list_draftsC
List Gmail drafts (most recent first).
Inputs: email, page_token, max_results.
gmail_list_labelsB
List all Gmail labels (system and user).
Inputs: email.
gmail_searchA
Search Gmail. Returns enriched metadata per match (from/subject/date/snippet/labelIds/hasAttachments) by default. Set format='ids' for the lighter ID-only response (cheaper, useful for piping to bulk ops).
Inputs: query (required), email, format, page_token, +1 more.
setup_add_accountA
Authorize an additional Google account. Call without url_or_code to get a consent URL, then call again with the post-consent localhost URL/code. Once multiple accounts are configured, Google tools require email on every call.
Inputs: email, url_or_code.
setup_authA
Authorize the first Google account or reauthorize an existing one. Call without url_or_code to begin, then call again with the post-consent localhost URL/code to finish. Requests Gmail, Calendar, read/write Google Docs and Sheets, and read-only Google Drive access. Existing accounts must reauthorize to grant newly added scopes.
Inputs: email, url_or_code.
setup_list_accountsA
List configured Google accounts and their granted OAuth scopes.
Inputs: no named parameters.
sheets_get_spreadsheetA
Get spreadsheet metadata, tab titles/IDs, dimensions, named ranges, and other properties. Cell grid data is excluded by default; enable it for formatting and restrict ranges for large spreadsheets. Discover spreadsheet IDs with drive_search_files using mimeType = 'application/vnd.google-apps.spreadsheet'.
Inputs: spreadsheet_id_or_url (required), email, ranges, include_grid_data.
sheets_read_valuesA
Read one or more ranges across spreadsheet tabs in one request. Returns valueRanges in requested order, with trailing empty rows/columns omitted. Choose FORMULA to inspect formulas or UNFORMATTED_VALUE for calculated numbers.
Inputs: ranges (required), spreadsheet_id_or_url (required), email, major_dimension, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 24 tools
Tools are largely distinct, with clear service prefixes and action verbs. Minor overlap exists between docs_get_document and docs_read_document (structured vs plain text) and between gmail_download_attachments and gmail_bulk_export (attachments vs full messages), but descriptions clarify the boundaries.
Names follow a consistent service_verb_noun snake_case convention (e.g., gmail_list_labels, calendar_get_event, drive_download_file). A few names omit the object (gmail_search, setup_auth) or use an adjective (gmail_bulk_export), but the pattern is still predictable.
24 tools span five Google services plus auth, averaging roughly 4 tools per service, which is reasonable for a broad multi-service server. Gmail (8) and Drive (6) are somewhat heavy, but each tool serves a distinct function.
The surface is heavily read-only: Gmail lacks send/draft-create/modify, Calendar lacks create/update/delete events, and Docs/Sheets lack any write operations despite auth requesting write scopes. These are significant gaps for a Google Workspace server.
Maintenance
Related MCP Connectors
Permissioned access to Gmail, Drive and Calendar via the user's own Google account
Gmail, Outlook, Drive, OneDrive and calendars for AI agents. Many accounts, one endpoint, audit log.
Multiple Gmail accounts, editable Google Sheets & Docs for AI agents. Deny-by-default access rules.
Hosted email MCP for your own Gmail, Outlook.com, Microsoft 365, iCloud or IMAP inbox: read, search, draft, reply in thread, forward and file mail. It moves or flags up to 500 messages in one call, and a send leaves exactly one copy in Sent. A calendar is a separate connection, and connecting one adds diary and scheduling tools.
Related MCP Servers
- AlicenseBqualityCmaintenanceMulti-account Google MCP server providing read access to Gmail and Calendar via stdio. Supports secure authentication for personal and work accounts with OAuth and keychain token storage.4MIT
- AlicenseNot gradedqualityBmaintenanceEnables local, read-only access to multiple Gmail and Google Drive accounts through explicit per-account aliases, using bring-your-own Google OAuth with secure credential storage and no telemetry or write capabilities.MIT
- AlicenseAqualityCmaintenanceEnables managing multiple Gmail accounts under one OAuth client, with per-account access levels, cross-account search, and read/write operations via stdio or Streamable HTTP.12298 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables Claude and Gemini to access and manage multiple Google accounts simultaneously across services such as Gmail, Drive, Calendar, YouTube, Sheets, Analytics, AdSense, and Fitness, with create, read, update, and delete operations. It runs locally without external intermediaries to keep account access private.MIT