google_workspace_mcp

Exposes 90+ tools across 12 Google Workspace services (Gmail, Drive, Calendar, Docs, Sheets, Slides, Forms, Tasks, Chat, Custom Search, Contacts, Apps Script) through a unified MCP protocol interface. Uses a ToolTierLoader system defined in tool_tiers.yaml that dynamically imports tool modules based on CLI arguments (--tool-tier core/extended/complete), enabling selective capability exposure to manage API quota consumption and complexity. The tool registry is populated at server startup via dictionary mapping in main.py that conditionally imports service-specific tool modules based on configuration.

Implements both OAuth 2.0 legacy flow and OAuth 2.1 with session management, selectable via CLI flag (--single-user for desktop OAuth 2.0, multi-user for OAuth 2.1 with session context). Handles credential storage via a pluggable storage backend system and manages authentication state through service-specific decorators that inject credentials into tool execution contexts. The authentication system supports both single-user desktop flows (where credentials are stored locally) and multi-user cloud deployments (where session tokens are managed server-side).

Exposes tools for sending messages to Chat spaces/direct messages, retrieving message history, and managing conversations with thread support. Uses Chat API's messages.create() to send messages with optional threading (parent message ID), and messages.list() to retrieve conversation history. Supports message formatting (bold, italic, code blocks) via Chat's message formatting syntax. Handles both space messages (group conversations) and direct messages (1-on-1 conversations).

Provides tools for creating contacts with name, email, phone, and custom fields, organizing contacts into groups, and retrieving contact information. Uses People API's people.createContact() and people.updateContact() to manage contact data, supporting custom fields for additional metadata. Handles contact groups via contactGroups.create() and contactGroups.update(). Retrieves contacts via people.listConnections() with optional filtering by group or search query.

Exposes tools for executing Google Apps Script functions deployed as web apps or bound to Workspace documents. Uses Apps Script API's scripts.run() to invoke custom functions with parameters, returning results or error details. Supports both synchronous execution (wait for result) and asynchronous patterns (trigger and poll). Handles error reporting with stack traces and execution logs. Enables Claude to extend Workspace capabilities with custom logic without modifying the MCP server.

Exposes tools for performing web searches using Google Custom Search Engine (CSE), with support for site-specific searches and result filtering. Uses Custom Search API's cse.list() to execute searches with optional site restrictions, returning ranked results with titles, snippets, and URLs. Supports pagination for large result sets and filtering by content type (web pages, images, PDFs). Enables Claude to search the web or specific sites for information without leaving the conversation.

Implements a transport abstraction layer that supports both stdio (for local MCP clients like Claude Desktop) and HTTP server modes (for remote clients). Uses SecureFastMCP class extending FastMCP to handle MCP protocol messages, with configurable transport via CLI flag (--transport stdio or streamable-http). The HTTP server mode exposes MCP endpoints for remote clients, while stdio mode communicates via stdin/stdout for local integration. Handles protocol serialization, message routing, and error responses transparently.

Implements a pluggable credential storage system that abstracts the underlying storage mechanism (filesystem, database, cloud secret manager). Supports multiple backend implementations configured via environment variables or configuration files, enabling operators to choose storage based on deployment requirements. Handles credential encryption, rotation, and secure retrieval. The abstraction layer allows new storage backends to be added without modifying core authentication logic.

Implements comprehensive error handling with automatic retry logic for transient failures (rate limits, temporary API outages). Uses exponential backoff strategy with jitter to avoid thundering herd problems when retrying failed requests. Distinguishes between retryable errors (429 rate limit, 503 service unavailable) and permanent errors (401 auth failure, 404 not found), applying appropriate recovery strategies. Includes configurable retry limits and backoff parameters to balance reliability with latency.

Provides tools for querying Gmail using Google's search syntax (labels, from:, to:, subject:, date ranges), retrieving full message threads with headers and body content, and composing/sending emails with attachment support. Implements thread-aware context retrieval that loads entire conversation histories, enabling AI assistants to understand email context before responding. Uses Gmail API's messages.list() with query parameters and messages.get() with format=full to extract structured message data including MIME parts, headers, and thread IDs.

Exposes tools for listing files/folders with recursive traversal, searching by name/MIME type, uploading files, creating folders, and managing sharing permissions. Uses Drive API's files.list() with pageToken-based pagination and supports recursive folder traversal via recursive queries or manual parent-child navigation. Permission management includes sharing files with users/groups, setting role-based access (viewer, commenter, editor), and managing public sharing settings. Implements efficient querying via MIME type filters and parent folder IDs to avoid full-drive scans.

Provides tools for creating calendar events with attendee lists, retrieving events within date ranges, updating event details, and managing attendee responses (accept/decline/tentative). Handles timezone conversion automatically by accepting timezone-aware datetime strings and converting to RFC 3339 format required by Calendar API. Supports recurring events via recurrence rules (RRULE), event notifications, and attendee availability queries. Uses Calendar API's events.insert(), events.get(), events.update(), and events.list() with time-based filtering.

Provides tools for creating new Google Docs, appending/inserting text content, applying formatting (bold, italic, headings), and retrieving document content with revision history. Uses Docs API's batchUpdate() method to execute multiple document mutations in a single request, enabling efficient multi-step edits. Supports collaborative features like suggestion mode (tracked changes) and comment insertion. Retrieves document structure including headings, tables, and formatting via the documents.get() method with full document representation.

Exposes tools for reading/writing cell ranges, executing formulas, applying data validation rules, and managing sheet structure (add/delete rows/columns). Uses Sheets API's batchUpdate() for efficient multi-cell operations and values.batchGet() for retrieving ranges. Supports formula insertion (e.g., =SUM(), =VLOOKUP()) with automatic recalculation, and data validation rules (dropdown lists, number ranges, custom formulas). Handles both A1 notation and grid coordinates for cell addressing.

Provides tools for creating presentations, adding slides with predefined layouts, inserting text/shapes, and managing slide properties. Uses Slides API's batchUpdate() to execute multiple slide mutations in a single request, supporting operations like adding text boxes, shapes, and images. Handles slide layouts (title slide, bullet points, blank) and theme application. Retrieves presentation structure including slide order, elements, and formatting via presentations.get().

Exposes tools for creating forms with various question types (multiple choice, short answer, paragraph, dropdown, linear scale), configuring conditional branching (show question based on previous answer), and retrieving form responses. Uses Forms API's batchUpdate() to create questions and configure form logic, and responses.list() to retrieve submitted responses. Supports form settings like required questions, answer shuffling, and response collection limits.

Provides tools for creating task lists, adding tasks with due dates and descriptions, organizing tasks into hierarchical subtasks, and managing task status (needs action, completed). Uses Tasks API's tasks.insert() and tasks.update() to create and modify tasks, supporting parent-child relationships for subtasks. Handles task properties like due dates, notes, and completion status. Retrieves task lists and tasks within lists via tasks.list() with optional filtering by status.