gsuite-mcp

Complete Google Workspace MCP server — Gmail, Calendar, Drive, Docs, Tasks, Sheets, Slides, Forms, Contacts, Meet, Drive Activity, and Chat. Single Go binary with true multi-account support.

Quick Start

→ Full Installation Guide — Get running in under 10 minutes

git clone https://github.com/aliwatters/gsuite-mcp.git
cd gsuite-mcp
./install.sh

# Authenticate
gsuite-mcp auth personal

# Add to your MCP client config

install.sh builds the MCP harness binary to ~/.local/libexec/gsuite-mcp and also installs a PATH/CLI copy at ~/.local/bin/gsuite-mcp. It skips a rebuild only when both installed binaries match HEAD. Re-run with --force or FORCE_REBUILD=1 to force a rebuild. Set INSTALL_PREFIX to change the install location.

Why gsuite-mcp?

• Multi-account: Switch accounts per-operation with "account": "work"
• Complete coverage: Gmail, Calendar, Drive, Docs, Tasks, Sheets, Slides, Forms, Contacts, Meet, Drive Activity, Chat
• Single binary: No Python, no Node, no runtime dependencies
• MCP native: JSON Schema 2020-12, proper tool descriptions

Feature	google-workspace	gsuite-mcp
Multi-account	User-level	Per-operation
JSON Schema	draft-07 (Claude errors)	2020-12
Services	Gmail only	Full Workspace
Runtime	Python + uv	Single Go binary
Batch operations	Limited	Full support

Tools Overview

Gmail (47 tools)

Full inbox management: search, read, send, reply, archive, trash, labels, filters, drafts, threads, batch operations, vacation responder, send-as aliases, delegation.

Calendar (12 tools)

Complete calendar control: list events, create/update/delete, recurring events, free/busy queries, Google Meet integration.

Drive (24 tools)

File management with shared drive support: search (with friendly file type filter), upload, download, list, create folders, move, copy, trash, delete, share, permissions, shareable links, comments & replies, version history (revisions).

Docs (29 tools)

Document creation and editing: create, read, structure, append, insert, replace, delete, formatting (bold, italic, headings, format-by-find), lists, tables, images, headers/footers, markdown export, PDF export, import, named ranges, suggested edits.

Tasks (10 tools)

Task management: lists, tasks, subtasks, due dates, completion, reordering.

Sheets (16 tools)

Spreadsheet operations: read, write, append, batch operations, create, cell formatting, conditional formatting, data validation, charts, pivot tables.

Slides (5 tools)

Presentation operations: get presentation metadata and structure, get individual slide details, slide thumbnails, create presentations, batch update (add/modify/delete slides, text, shapes, images).

Forms (5 tools)

Form management: get form structure and questions, create forms, batch update (add/update/delete questions, settings), list responses, get individual responses.

Contacts (12 tools)

Contact management: list, search, create, update, delete, contact groups.

Meet (6 tools)

Conference record retrieval: list/get conference records, list participants, list/get transcripts, get transcript entries for meeting summarization.

Drive Activity (1 tool)

Audit trail queries: query activity history for Drive files and folders (who edited, created, moved, shared, with time range and action type filters).

Chat (9 tools)

Google Chat management: list/get/create spaces, list/get/send messages, thread replies, add/remove reactions, list space members.

Gmail Core

Tool	Description
gmail_search	Search messages with Gmail query syntax
gmail_get	Get single message with full content
gmail_get_message	Alias for gmail_get
gmail_get_messages	Batch get messages (max 25)
gmail_get_thread	Get full conversation thread
gmail_send	Send new email, optionally with local attachments
gmail_reply	Reply to existing thread, optionally with local attachments
gmail_draft	Create draft, optionally with local attachments
gmail_list_labels	List all labels with counts

Header detail on gmail_get/gmail_get_message/gmail_get_messages/gmail_get_thread/gmail_get_draft (breaking change): these tools return a curated, lowercase headers map whenever Gmail returns a message payload (format: "minimal" returns none) (date, from, to, cc, bcc, subject, message-id, reply-to, sender, delivered-to, x-original-to, return-path, in-reply-to, references, list-unsubscribe, list-unsubscribe-post, list-id, auto-submitted, precedence, content-type, authentication-results, received-spf, plus dkim-signature=present when available). Gmail's full ordered raw MIME header list — payload_headers, which preserves repeated headers like multiple Received lines — is no longer included by default. Pass headers: "raw" to opt in for SPF/DKIM/ARC debugging; a batch of messages with payload_headers inlined can blow past output size limits (#199). body_format defaults to "text", which already returns just the decoded plain-text body with no MIME multipart scaffolding.

Gmail Management

Tool	Description
gmail_modify_message	Add/remove labels
gmail_archive	Remove from inbox
gmail_trash / gmail_untrash	Move to/from trash
gmail_mark_read / gmail_mark_unread	Mark read status
gmail_star / gmail_unstar	Star/unstar
gmail_spam / gmail_not_spam	Spam management

Gmail Batch

Tool	Description
gmail_batch_modify	Batch label changes
gmail_batch_archive	Archive multiple
gmail_batch_trash	Trash multiple

Gmail URL / Web-ID Resolution

Tool

Description

gmail_resolve_web_id

Resolve a Gmail web-UI ID (from a browser URL) to API message/thread IDs. Accepts a full Gmail URL (https://mail.google.com/mail/u/0/#inbox/FMfcg…) or bare ID in any form: FMfcg… (current), thread-f:<decimal> (legacy), msg-f:<decimal> (legacy), or an already-API hex ID. FMfcg… candidates are validated against the selected account before IDs are returned; if validation fails, use gmail_search with subject, sender, or date terms.

Example:

gmail_resolve_web_id(id="https://mail.google.com/mail/u/0/#inbox/FMfcgzQgLrxVJjTVKwvFRgbdLPFsxXfj")
# → { thread_id: "552634d52b0bc546", message_id: "6dd2cf16cc577e3", id_kind: "FMfcg" }
# If those decoded IDs are not fetchable for the selected account, the tool returns
# an explicit error recommending gmail_search instead of returning unusable IDs.

gmail_resolve_web_id(id="thread-f:1821570065795440641")
# → { thread_id: "19478452e138e001", id_kind: "thread-f" }

Gmail Extended

Tool	Description
gmail_get_attachment	Download attachment as base64 data
gmail_list_attachments	List downloadable attachments on a message (part_id is the stable handle)
gmail_download_attachment	Save a message attachment to a local file (select by part_id)
gmail_list_filters / gmail_create_filter / gmail_delete_filter	Filter management
gmail_create_label / gmail_update_label / gmail_delete_label	Label management
gmail_list_drafts / gmail_get_draft / gmail_update_draft / gmail_delete_draft / gmail_send_draft	Draft management
gmail_thread_archive / gmail_thread_trash / gmail_thread_untrash / gmail_modify_thread	Thread operations
gmail_get_profile	Account info
gmail_get_vacation / gmail_set_vacation	Vacation responder
gmail_list_send_as / gmail_get_send_as	List/get send-as aliases
gmail_create_send_as / gmail_update_send_as / gmail_delete_send_as	Manage send-as aliases
gmail_verify_send_as	Verify external send-as alias
gmail_list_delegates / gmail_create_delegate / gmail_delete_delegate	Delegation management

Calendar

Tool	Description
calendar_list_events	List events with filtering (supports event_types filter)
calendar_get_event	Get event details (includes conference data)
calendar_create_event	Create event (with optional Google Meet)
calendar_update_event	Update event
calendar_delete_event	Delete event
calendar_list_calendars	List available calendars
calendar_quick_add	Create from natural language
calendar_free_busy	Query availability across calendars
calendar_list_instances	List recurring event instances
calendar_update_instance	Update single recurrence
calendar_create_focus_time	Create Focus Time with auto-decline
calendar_create_out_of_office	Create Out of Office with auto-decline

Drive

Tool	Description
drive_search	Search files with query syntax (includes shared drives)
drive_get	Get file metadata
drive_download	Download file content (text or base64)
drive_upload	Upload new file from inline content or a local file_path (resumable streaming); returns id, name, size, md5Checksum
drive_update_file	Replace a file's body and/or rename it (no delete)
drive_list	List files in folder (optional exact name filter; returns size and md5Checksum)
drive_create_folder	Create folder
drive_move	Move file to different folder
drive_copy	Copy a file
drive_trash	Move file to trash
drive_delete	Permanently delete file
drive_share	Share file with users
drive_get_permissions	Get file permissions
drive_get_shareable_link	Get shareable URL with sharing status
drive_list_comments	List comments on a file
drive_get_comment	Get a specific comment
drive_create_comment	Create a comment
drive_update_comment	Update a comment
drive_delete_comment	Delete a comment
drive_list_replies	List replies on a comment
drive_create_reply	Reply to a comment
drive_list_revisions	List file version history
drive_get_revision	Get revision metadata
drive_download_revision	Download a specific revision

Docs

Tool	Description
docs_create	Create new document
docs_get	Get content as plain text
docs_get_metadata	Get title, word count
docs_get_structure	Get document structure with character indices
docs_append_text	Append to end
docs_insert_text	Insert at position
docs_replace_text	Find and replace
docs_delete_text	Delete range
docs_insert_table	Insert table
docs_insert_link	Insert hyperlink
docs_format_text	Bold, italic, color, font
docs_format_by_find	Find text and apply formatting (no position math)
docs_clear_formatting	Remove formatting
docs_set_paragraph_style	Headings, alignment
docs_create_list / docs_remove_list	Bullet/numbered lists
docs_insert_page_break	Page breaks
docs_insert_image	Insert image from URL
docs_create_header / docs_create_footer	Headers/footers
docs_batch_update	Raw API access
docs_get_as_markdown	Get content as markdown
docs_find_and_replace	Find and replace text
docs_export_to_pdf	Export Doc/Sheet/Slides to PDF
docs_import_to_google_doc	Import text/HTML/markdown as Google Doc
docs_list_named_ranges	List all named ranges in a document
docs_create_named_range	Create a named range (stable editing anchor)
docs_delete_named_range	Delete a named range by ID
docs_get_suggested_edits	Get suggested edits (insertions, deletions, formatting)

Tasks

Tool	Description
tasks_list_tasklists	List all task lists
tasks_list	List tasks in a list
tasks_get	Get task details
tasks_create	Create task
tasks_update	Update task
tasks_complete	Mark complete
tasks_delete	Delete task
tasks_create_tasklist / tasks_update_tasklist / tasks_delete_tasklist	Task list management
tasks_move	Reorder or make subtask
tasks_clear_completed	Clear completed

Sheets

Tool	Description
sheets_get	Get spreadsheet metadata
sheets_read	Read cell range
sheets_write	Write to cells
sheets_append	Append rows
sheets_create	Create spreadsheet
sheets_batch_read	Read multiple ranges
sheets_batch_write	Write multiple ranges
sheets_clear	Clear cell range
sheets_format_cells	Background, font, bold, alignment, number format
sheets_add_conditional_format	Boolean or gradient formatting rules
sheets_add_data_validation	Dropdowns, number constraints, custom formulas
sheets_create_chart	Create embedded chart (bar, line, pie, etc.)
sheets_update_chart	Update chart title or type
sheets_delete_chart	Delete embedded chart
sheets_create_pivot_table	Create pivot table for data summarization
sheets_batch_update	Raw API access for advanced operations

Contacts

Tool	Description
contacts_list	List all contacts
contacts_get	Get contact details
contacts_search	Search contacts
contacts_create	Create contact
contacts_update	Update contact
contacts_delete	Delete contact
contacts_list_groups	List contact groups
contacts_get_group	Get group with members
contacts_create_group / contacts_update_group / contacts_delete_group	Group management
contacts_modify_group_members	Add/remove from group

Slides

Tool	Description
slides_get_presentation	Get presentation metadata, slide list with text previews
slides_get_page	Get full details of a single slide (shapes, images, tables, text)
slides_get_thumbnail	Get slide thumbnail image URL
slides_create	Create new presentation
slides_batch_update	Batch update (add/modify/delete slides, text, shapes, images)

Forms

Tool	Description
forms_get	Get form metadata, questions, and structure
forms_create	Create new form
forms_batch_update	Batch update (add/update/delete questions, settings)
forms_list_responses	List all form responses
forms_get_response	Get a single form response

Meet

Tool	Description
meet_list_conference_records	List conference records visible to the user
meet_get_conference_record	Get a specific conference record
meet_list_participants	List participants of a conference
meet_list_transcripts	List transcripts for a conference
meet_get_transcript	Get transcript details
meet_list_transcript_entries	Get transcript text entries for summarization

Drive Activity

Tool	Description
driveactivity_query	Query activity history for a Drive file or folder

Chat

Tool	Description
chat_list_spaces	List Chat spaces
chat_get_space	Get space details
chat_create_space	Create a new space
chat_list_messages	List messages in a space
chat_get_message	Get a specific message
chat_send_message	Send a message to a space
chat_create_reaction	Add a reaction to a message
chat_delete_reaction	Remove a reaction
chat_list_members	List members of a space

Usage Examples

Non-interactive tool calls

Scripts can invoke registered tools directly. The call command does not start a browser or an auth server; authenticate separately with gsuite-mcp auth <email> when needed. Results are JSON on stdout, and errors are written to stderr. Exit codes are 0 for success, 1 for tool or argument errors, and 2 when authentication is required.

gsuite-mcp call drive_list --account user@example.com --args '{"folder_id":"root"}'
gsuite-mcp call drive_upload --account user@example.com --args-file upload-args.json

For uploads, pass file_path in the JSON arguments to stream a local file without loading it into the argument string. drive_list and drive_search return next_page_token (empty when complete) and truncated so scripts can follow every page.

Multi-Account

All tools accept an optional account parameter:

{"query": "is:unread", "account": "work"}
{"message_id": "abc123", "account": "personal"}
{"query": "from:amazon"}  // uses default account

Common Workflows

1. gmail_search({"query": "is:unread", "account": "support"})
2. gmail_get({"message_id": "...", "account": "support"})
3. gmail_reply({"message_id": "...", "body": "Thanks for reaching out...", "attachments": ["/abs/path/to/form.pdf"]})
4. gmail_batch_archive({"message_ids": [...]})

To inspect an inbound attachment:

1. gmail_list_attachments({"message_id": "...", "account": "support"})
2. gmail_download_attachment({"message_id": "...", "part_id": "1", "output_dir": "~/Desktop", "account": "support"})

part_id is the stable handle. Gmail mints a new attachment_id on every read, so two listings of the same message report different attachment_id values for the same file. Earlier tokens keep working — gmail_download_attachment passes an attachment_id it does not recognise straight to the Gmail API rather than rejecting it — but part_id is what you can hold on to and compare. When a message has exactly one attachment, both selectors can be omitted.

calendar_create_event({
  "summary": "Team Standup",
  "start_time": "2024-02-05T09:00:00-08:00",
  "end_time": "2024-02-05T09:30:00-08:00",
  "attendees": ["colleague@example.com"],
  "add_conferencing": true
})

1. docs_create({"title": "Project Report"})
2. docs_append_text({"document_id": "...", "text": "Project Report\n\nIntroduction..."})
3. docs_set_paragraph_style({"document_id": "...", "start_index": 1, "end_index": 15, "named_style_type": "TITLE"})

For AI Agents

If you're an AI agent or building integrations, see docs/AGENTS.md for:

• Project architecture and patterns
• Tool registration patterns
• Error handling conventions
• Testing guidelines

Natural Language Prompts

These prompts work well with gsuite-mcp:

• "Show my unread emails"
• "What meetings do I have today?"
• "Send an email to X about Y"
• "Create a task to review the PR by Friday"
• "Add a new contact for John Smith"
• "What's on my work calendar this week?" (uses account parameter)

Configuration

See INSTALLATION.md for full setup instructions.

Config location: ~/.config/gsuite-mcp/

~/.config/gsuite-mcp/
├── client_secret.json      # Your OAuth app credentials
├── config.json             # Settings (optional — created by `gsuite-mcp init`)
└── credentials/
    └── {email}.json        # Per-account tokens

OAuth Callback Port

The default OAuth callback port is 38917. Override it in config.json:

{ "oauth_port": 9000 }

Or via environment variable: GSUITE_MCP_OAUTH_PORT=9000

Vendor-Neutral OAuth Token Command Hook

Set GSUITE_OAUTH_TOKEN_CMD to supply OAuth refresh tokens from any external secret source (password manager, vault, environment injection — any tool that can print a token to stdout).

Contract:

• The command receives the account identifier (email address) as its first argument.
• It must print the OAuth refresh token to stdout and exit 0.
• Non-zero exit = failure; gsuite-mcp logs the exit code and stderr, then returns a clear error.

# Example: use any secret-retrieval tool that accepts an account id and prints a token
export GSUITE_OAUTH_TOKEN_CMD="my-secret-tool get-oauth-token"

# gsuite-mcp will call: my-secret-tool get-oauth-token user@example.com
# and use the token printed to stdout as the OAuth refresh token for that account.

When GSUITE_OAUTH_TOKEN_CMD is not set, gsuite-mcp reads tokens from local JSON files in the credentials directory (default behaviour — unchanged). The env var is process-wide: all accounts use the hook when it is set.

The hook is secret-manager agnostic. It works with 1Password CLI, HashiCorp Vault, pass, environment injection, or any other tool that follows the contract above.

Drive Access Filtering

Restrict which shared drives are accessible via MCP tools. Add drive_access to config.json:

{
  "oauth_port": 38917,
  "drive_access": {
    "allowed": ["Marketing", "Engineering"]
  }
}

Modes (choose one):

• Allowlist: "allowed": ["Drive A", "Drive B"] — only these shared drives + My Drive
• Blocklist: "blocked": ["SENSITIVE", "HR"] — everything except these drives

My Drive is always accessible. Setting both allowed and blocked is an error. Drives can be specified by name (case-insensitive) or ID. The filter applies to Drive, Docs, and Sheets tools.

HTTP Auth Endpoint (MCP Server Mode)

When running as an MCP server, gsuite-mcp starts a persistent HTTP server on the OAuth port so agents and users can trigger re-authentication from a browser:

• http://localhost:38917/auth — starts OAuth flow (opens Google consent screen)
• http://localhost:38917/auth?account=user@gmail.com — pre-selects the Google account

When a tool encounters missing credentials, the error message includes a clickable auth URL. If the port is unavailable, the MCP server continues without the auth endpoint.

Development

go build -o gsuite-mcp ./cmd/gsuite-mcp
go test ./...
go vet ./...

E2E Tests

End-to-end tests run against live Google APIs using a dedicated test account. They are excluded from normal go test runs via the e2e build tag.

Setup:

1. Authenticate the test account: ./gsuite-mcp auth testaccount@gmail.com
2. Create .env in the project root (see e2e/.env.example):

   E2E_TEST_ACCOUNT=testaccount@gmail.com
   

Run:

go test -tags=e2e -v -count=1 ./e2e/...

Tests create temporary artifacts (emails, labels, events, files, task lists) and clean up after themselves. The test account should be a dedicated account, not a production mailbox.

See docs/AGENTS.md for contribution guidelines.

Releases

gsuite-mcp uses a patch-first versioning policy — an intentional deviation from strict SemVer:

Change type	Bump
Bug fix	patch
Small / low-risk additive feature (e.g. a new optional parameter)	patch
Larger feature set (multiple tools, new service area)	minor
Breaking change (removed/renamed tool or param, behavior change)	major

See RELEASING.md for the full policy, rationale, and release process.

Roadmap

See docs/ROADMAP.md for planned features and development phases.

License

MIT