@geobio/google-workspace-server

Exposes Google Workspace resources (Docs, Sheets, Slides, Drive) as MCP tools through a standardized protocol server. Implements the Model Context Protocol specification to translate Claude/LLM tool calls into authenticated Google Workspace API requests, handling OAuth2 credential management and resource serialization into context-compatible formats for LLM consumption.

Fetches Google Docs documents by ID and converts them to plain text or markdown format for LLM consumption. Uses Google Docs API to parse document structure (headings, lists, tables, formatting) and serializes into a flat text representation that preserves semantic structure while remaining context-efficient for token budgets.

Queries Google Sheets by sheet ID and range, returning cell values in structured JSON format. Implements range-based queries (e.g., 'Sheet1!A1:C10') using Google Sheets API to fetch live data, with optional header row detection for converting rows into key-value objects for easier LLM reasoning over tabular data.

Lists files and folders in Google Drive with filtering and search capabilities. Uses Google Drive API to query file metadata (name, type, modification date, owner) and supports MIME type filtering to find specific document types (Docs, Sheets, PDFs, etc.). Results are paginated and can be filtered by folder or search query.

Extracts text content from Google Slides presentations by slide ID. Uses Google Slides API to retrieve slide layouts and text elements, converting them into a sequential text representation that preserves slide order and speaker notes for LLM analysis of presentation content.

Registers Google Workspace capabilities as MCP tools with standardized JSON schemas. Implements the MCP tool definition spec to expose document access, sheet queries, and file search as callable tools with parameter schemas, descriptions, and error handling. Clients discover available tools via the MCP protocol handshake.

Handles Google OAuth2 authentication flow including credential storage, token refresh, and expiration management. Implements automatic token refresh before expiration to ensure uninterrupted API access. Supports both user credentials (via OAuth2 consent flow) and service account credentials for different deployment scenarios.

Implements structured error handling for Google API failures including rate limiting, authentication errors, and resource not found scenarios. Returns MCP-compliant error responses with descriptive messages and suggests recovery actions (retry, re-authenticate, check permissions). Includes exponential backoff for transient failures.