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 (core/tool_tier_loader.py) that dynamically imports tool modules based on CLI-specified tiers (core/extended/complete), allowing selective API exposure to manage quota consumption and complexity. Tools are registered in a dictionary mapping (main.py 176-187) and loaded at server startup, with each service module implementing standardized tool patterns for consistent MCP schema generation.

Implements dual OAuth authentication modes (OAuth 2.0 legacy flow and OAuth 2.1 with session management) via service authentication decorators that inject credentials into tool execution contexts. Credentials are stored persistently (location configurable via storage backend) and session context is maintained across tool calls, eliminating per-call re-authentication. The authentication system (core/auth.py) handles token refresh, expiration, and multi-user credential isolation in cloud deployments. Single-user mode (--single-user flag) uses local credential storage; multi-user mode requires external session storage (Redis, database) for credential isolation.

Provides 6+ Chat tools for sending messages to spaces and direct messages, retrieving conversation history, and managing chat spaces. Tools support message formatting (bold, italic, links) and file attachments. Chat operations include creating spaces, adding members, and retrieving message threads. The Chat module (tools/chat.py) handles message threading and implements pagination for conversation history. Supports both direct messages (DM) and space-based conversations.

Implements dual transport modes for MCP server deployment: stdio (for local/desktop use) and streamable-http (for cloud/multi-user deployments). The SecureFastMCP class (core/server.py) extends FastMCP and configures transport based on CLI flag (--transport). Stdio mode pipes JSON-RPC requests/responses through standard input/output for Claude Desktop integration. Streamable-http mode exposes an HTTP server (configurable port) for remote client connections. Both modes support the same MCP protocol and tool registry. The server initialization (main.py) handles transport selection and startup.

Implements automatic retry logic with exponential backoff for transient API failures (rate limits, quota exhaustion, temporary service unavailability). The error handling system (core/error_handling.py or integrated in tool modules) detects quota-related errors from Google APIs and automatically retries with increasing delays (1s, 2s, 4s, 8s, etc.). Maximum retry attempts are configurable (default 3). Non-transient errors (authentication failures, invalid parameters) fail immediately without retry. Retry metadata is included in error responses to inform clients of retry attempts.

Exposes 2+ Custom Search tools that integrate with Google Custom Search Engine (CSE) for web search and result ranking. Tools support search queries with optional filters (site:, filetype:) and return ranked results with metadata (title, URL, snippet, rank). The Custom Search module (tools/custom_search.py) uses the Custom Search API for server-side query execution and result ranking. Results are limited to top 10 by default (configurable). Supports both web search and image search modes.

Provides 4+ Contacts tools for retrieving contact information from Google Contacts directory, including name, email, phone, and organization metadata. Tools support contact search by name or email and batch retrieval of contact lists. The Contacts module (tools/contacts.py) uses the People API to access contact data with structured metadata extraction. Supports filtering by contact group (personal, work, etc.). Contact creation and editing are not supported (read-only access).

Exposes 3+ Apps Script tools for executing Apps Script functions and managing script deployments. Tools support function execution with parameters and return value retrieval. The Apps Script module (tools/apps_script.py) uses the Apps Script API to execute scripts and retrieve execution results. Supports both synchronous and asynchronous function execution. Script deployments can be listed and managed. Execution errors are captured and returned with stack traces.

Provides 15+ Gmail-specific tools including message search with advanced filters (from, to, subject, date range, labels), message composition with attachments, label creation/management, and thread operations. Tools use the Gmail API's query language for server-side filtering, reducing data transfer. Message retrieval returns structured metadata (sender, subject, date, labels) with optional full body/attachments. Label operations support hierarchical organization. The Gmail tool module (tools/gmail.py) implements common patterns: query building, pagination, error handling for quota limits, and automatic retry on transient failures.

Exposes 12+ Calendar tools for event creation, retrieval, updates, and deletion with built-in conflict detection and availability checking. Tools query calendar events within date ranges, extract attendee lists, and check for scheduling conflicts before creating new events. The Calendar module (tools/calendar.py) uses the Calendar API's freebusy endpoint for efficient availability queries without fetching full event details. Event creation supports recurrence rules (RRULE), attendee invitations, and reminder configuration. Supports multiple calendar access (primary and secondary calendars).

Provides 18+ Drive tools for file/folder operations including advanced search with filters (name, type, owner, modified date), file upload/download, metadata extraction (size, MIME type, permissions), and permission management (share, revoke access). Search uses Drive API's query language for server-side filtering. File operations support batch processing (list 100+ files). Permission management includes role-based access control (viewer, commenter, editor, owner). The Drive module (tools/drive.py) handles file streaming for large uploads/downloads and implements pagination for result sets.

Exposes 8+ Docs tools for document creation, content retrieval, text insertion, and basic formatting operations. Tools use the Docs API's batchUpdate mechanism for atomic multi-step edits (insert text, apply formatting, update styles in single request). Document content is retrieved as structured text with formatting metadata. Text insertion supports position-based insertion (at specific character offset) and search-and-replace operations. Formatting includes bold, italic, underline, and heading styles. The Docs module (tools/docs.py) handles document structure parsing and implements error handling for concurrent edit conflicts.

Provides 12+ Sheets tools for spreadsheet operations including cell read/write, range operations, formula insertion, and data retrieval. Tools use the Sheets API's batchUpdate for atomic multi-cell updates. Data retrieval supports range queries (A1:Z100 notation) and returns structured data (values, formulas, formatting). Cell writes support formulas, numbers, text, and dates. The Sheets module (tools/sheets.py) implements automatic type detection (formula vs literal value) and includes error handling for invalid ranges and circular references. Supports multiple sheet tabs within a workbook.

Exposes 6+ Slides tools for presentation creation, slide management, and content insertion (text, shapes, images). Tools use the Slides API's batchUpdate for atomic multi-element edits. Slide operations include adding/removing slides, inserting text boxes and shapes, and applying basic formatting. The Slides module (tools/slides.py) handles slide layout selection and element positioning. Content insertion supports text with formatting (bold, italic, color) and shape insertion with styling. Supports multiple slide layouts (title slide, content slide, blank).

Provides 5+ Forms tools for form creation, question insertion, and response retrieval. Tools support multiple question types (multiple choice, short answer, paragraph, dropdown, linear scale). Form creation uses the Forms API's batchUpdate for atomic form structure definition. Response retrieval returns structured data (question ID, answer text, timestamp). The Forms module (tools/forms.py) handles question validation and response parsing. Supports form sharing and link generation for distribution.

Exposes 8+ Tasks tools for task creation, retrieval, updates, and list management with hierarchical organization (parent-child task relationships). Tools support task status tracking (needsAction, completed), due dates, and notes. Task lists can be created and organized hierarchically. The Tasks module (tools/tasks.py) handles task completion status updates and implements pagination for large task lists. Supports moving tasks between lists and updating task metadata (title, notes, due date).