📋

Gsuite MCP

Complete Google Workspace MCP server — Gmail, Calendar, Docs, Tasks, Sheets, Contacts, Drive. Single Go binary with multi-account support.

0 installs

1 stars

1 forks

Trust: 56 — Fair

Productivity

Installation

npx gsuite-mcp

Ask AI about Gsuite MCP

I know everything about Gsuite MCP. Ask me about installation, configuration, usage, or troubleshooting.

0/500

Loading tools...

Reviews

Documentation

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 binary to ~/.local/bin/gsuite-mcp and skips a rebuild if the installed version already matches 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

Comparison with google-workspace MCP

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 (45 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 (23 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.

Full tool reference

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
`gmail_reply`	Reply to existing thread
`gmail_draft`	Create draft
`gmail_list_labels`	List all labels with counts

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 Extended

Tool	Description
`gmail_get_attachment`	Download attachment
`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
`drive_list`	List files in folder
`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

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

Email triage

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..."})
4. gmail_batch_archive({"message_ids": [...]})

Schedule a meeting

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
})

Create a formatted document

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

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
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:

Authenticate the test account: ./gsuite-mcp auth testaccount@gmail.com
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.

Roadmap

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

License

MIT