claude-google-sheets

This MCP server exposes a Claude-friendly interface to manage Google Sheets via MCP. It provides a suite of tools to discover spreadsheets, read and write data, and manage sheet metadata. After you configure Claude CLI to point at this MCP server, you can operate through natural language prompts or the provided slash commands. Common tasks include listing all spreadsheets, searching for sheets by name or owner, reading ranges, writing or appending data to ranges, and clearing ranges with safeguards. The server supports multiple authentication methods (OAuth 2.0, Service Account, and Application Default Credentials) and automatically handles token refreshes and caching for seamless automation.

Tools available include: list_spreadsheets (to enumerate your Sheets), search_spreadsheets (advanced search with filters), get_spreadsheet_info (metadata), read_range (read data from a specified range), write_range (write data with inferred types), append_data (append rows), and clear_range (clear contents with safeguards). Use natural language like “List all spreadsheets” or slash commands such as /list-sheets for quick access. The server is optimized for Claude CLI workflows and includes automatic configuration and slash command integration to streamline setup and usage.

Prerequisites:\n- Python 3.11 or higher installed on your system\n- Git installed to clone the repository\n- Optional: Claude CLI (for end-to-end integration)\n\nStep-by-step installation:\n1) Clone the repository:\nbash\ngit clone https://github.com/ryanrobson/claude-google-sheets-mcp.git\ncd claude-google-sheets-mcp\n\n2) Create and activate a Python virtual environment:\nbash\npython -m venv venv\n# macOS/Linux\nsource venv/bin/activate\n# Windows\nvenv\Scripts\activate\n\n3) Install the package in editable mode (and dev dependencies if you want tests and linting):\nbash\npip install -e ".[dev]"\n\n4) Run the interactive setup or start the server directly:\nbash\n# Interactive setup (recommended)\nclaude-google-sheets-mcp --setup\n\n# Or run the server module directly (for manual testing):\npython -m claude_google_sheets.server\n\n5) Add to Claude CLI configuration (example):\njson\n{\n \"mcpServers\": {\n \"google-sheets\": {\n \"command\": \"/path/to/venv/bin/python\",\n \"args\": [\n \"-m\",\n \"claude_google_sheets.server\"\n ]\n }\n }\n}\n\n6) (Optional) Install slash commands if you want Claude CLI integration:\nbash\./install-slash-commands.sh\n

Environment variables and configuration tips:\n- GOOGLE_SHEETS_CREDENTIALS: Path or JSON string for credentials. Supports OAuth, Service Account, or ADC; ensure the service account has access to the target sheets.\n- If you encounter authentication issues, use the interactive setup wizard (claude-google-sheets-mcp --setup) to guide you through selecting an auth method.\n- When using read/write operations, be mindful of Google Sheets API quotas and rate limits. The MCP tools map closely to common Sheet operations (list_spreadsheets, read_range, write_range, append_data, clear_range) and expose parameters like spreadsheet_id, range, values, and options for value rendering or input.\n- For production deployments, consider placing credentials in a secure location and restricting access to the server instance.\n- You can mix natural language commands with slash commands for robust workflows (e.g., “List spreadsheets owned by my team” or /read-sheet with the same target).