Claude Google Sheets Server

License: MIT Python 3.11+ MCP Compatible

A comprehensive Model Context Protocol (MCP) server for Google Sheets integration with Claude. This server provides intuitive access to Google Sheets operations, including spreadsheet discovery, data manipulation, and formatting - specifically optimized for Claude CLI.

🚀 One-command installation with full Claude CLI automation!

✨ Features

🔍 Spreadsheet Discovery

• List all spreadsheets in your Google Drive
• Advanced search with filters (name, owner, date, sharing status)
• Detailed metadata about any spreadsheet
• Find sheets by name with partial matching

📊 Data Operations

• Read data from any range with multiple format options
• Write data to specific ranges with type inference
• Append rows safely without overwriting existing data
• Clear ranges with confirmation safeguards

🚀 Fully Automated Setup

• One-command installation - Complete Claude CLI integration in minutes
• Automatic configuration - No manual JSON editing required
• 8 slash commands included - /list-sheets, /read-sheet, /write-sheet, etc.
• Universal authentication - Works with any Google account type
• Smart detection - Automatically finds and configures Claude CLI

🔐 Universal Authentication

• Works with any Google account type: Personal, GCP, Google Workspace/GSuite
• Interactive setup wizard for guided authentication configuration
• Multiple auth methods: OAuth 2.0, Service Account, Application Default Credentials
• Automatic token refresh and secure caching
• Smart account detection and permission checking

🚀 Quick Start

Prerequisites

• Python 3.11 or higher
• Claude CLI installed
• A Google account (personal, GCP, or Google Workspace/GSuite)

Installation

🔥 One-Command Setup (Recommended)

For completely automated installation including Claude CLI configuration, slash commands, and authentication setup:

git clone https://github.com/ryanrobson/claude-google-sheets-mcp.git
cd claude-google-sheets-mcp
./install-claude-cli.sh

This script will:

• ✅ Install all dependencies
• ⚙️ Automatically configure Claude CLI
• 📝 Install all 8 slash commands
• 🔐 Guide you through authentication setup
• 🧪 Test the installation

Manual Installation

If you prefer step-by-step control:

1. Clone the repository:

   git clone https://github.com/ryanrobson/claude-google-sheets-mcp.git
   cd claude-google-sheets-mcp
   

2. Install the server:

   ./install.sh
   

3. Run the interactive setup wizard:

   source venv/bin/activate
   claude-google-sheets-mcp --setup
   

4. Add to Claude CLI configuration (manual):

   {
     "mcpServers": {
       "google-sheets": {
         "command": "/path/to/claude-google-sheets-mcp/venv/bin/python",
         "args": [
           "-m",
           "claude_google_sheets.server"
         ]
       }
     }
   }
   

5. Install slash commands (optional):

   ./install-slash-commands.sh
   

📖 Usage

Natural Language Commands

Once configured, interact with Google Sheets using natural language:

List all my spreadsheets
Read data from range A1:C10 in my Budget spreadsheet
Write this sales data to my Q4 Results sheet
Search for spreadsheets containing 'project' in the name
Get information about my expense tracking sheet

Slash Commands (Power User)

For faster access to common operations:

• /list-sheets - List all your Google Sheets
• /read-sheet - Read data from a sheet range
• /write-sheet - Write data to a sheet range
• /append-sheet - Append new rows to a sheet
• /search-sheets - Search sheets with advanced filters
• /sheet-info - Get detailed sheet information
• /find-sheet - Find sheet by name
• /clear-range - Clear data from range (with confirmation)

📚 See SLASH_COMMANDS.md for detailed usage guide

🔐 Authentication

The Google Sheets MCP server supports all Google account types and provides an interactive setup wizard to guide you through the authentication process.

Quick Setup (Recommended)

Run the interactive setup wizard:

claude-google-sheets-mcp --setup

The wizard will:

• Detect your account type (Personal, Google Workspace, or GCP)
• Guide you through the appropriate authentication method
• Test your configuration to ensure everything works
• Provide troubleshooting tips if needed

Authentication Methods

🔐 OAuth 2.0 (Best for personal use)

• Access your personal Google Sheets
• Requires one-time Google Cloud project setup
• Interactive browser-based authentication
• Automatic token refresh

🤖 Service Account (Best for automation/server use)

• Non-interactive authentication for scripts
• Requires sharing sheets with service account email
• Ideal for team/organization deployments

🌐 Application Default Credentials (Best for GCP users)

• Uses existing gcloud authentication
• Perfect if you're already using Google Cloud Platform
• Quick setup with: gcloud auth application-default login --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/spreadsheets,https://www.googleapis.com/auth/drive"

Manual Setup (Advanced)

If you prefer manual configuration, see the setup wizard prompts for detailed instructions, or place your credentials in ~/.config/google-sheets-mcp/:

• OAuth: credentials.json (from Google Cloud Console)
• Service Account: service-account.json (service account key)
• Application Default: Use gcloud auth application-default login

🛠️ Available Tools

The MCP server exposes these tools:

Tool	Description	Parameters
list_spreadsheets	List all Google Sheets	max_results, query, include_shared
search_spreadsheets	Advanced spreadsheet search	name_contains, owner_email, created_after, etc.
get_spreadsheet_info	Get detailed metadata	spreadsheet_id
read_range	Read data from range	spreadsheet_id, range, value_render_option
write_range	Write data to range	spreadsheet_id, range, values, value_input_option
append_data	Append rows to sheet	spreadsheet_id, range, values
clear_range	Clear data from range	spreadsheet_id, range

🏗️ Architecture

claude-google-sheets-mcp/
├── src/claude_google_sheets/
│   ├── auth/                 # Authentication management
│   ├── tools/               # MCP tool implementations
│   ├── core/                # Base classes and utilities
│   └── server.py            # Main MCP server
├── slash-commands/          # Claude CLI slash commands
├── tests/                   # Test suite
└── docs/                    # Documentation

🧪 Development

Setup Development Environment

git clone https://github.com/ryanrobson/claude-google-sheets-mcp.git
cd claude-google-sheets-mcp
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[dev]"

Run Tests

python test_server.py

Code Quality

black src/
isort src/
flake8 src/
mypy src/

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Quick Contribution Guide

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Add tests for new functionality
5. Run the test suite: python test_server.py
6. Commit your changes: git commit -m 'Add amazing feature'
7. Push to the branch: git push origin feature/amazing-feature
8. Open a Pull Request

📋 Roadmap

• Formatting tools - Cell formatting, colors, borders
• Chart creation - Generate charts from data
• Batch operations - Multiple operations in single request
• Sheet management - Create, delete, rename sheets
• Collaboration features - Comments, suggestions
• Advanced formulas - Formula manipulation and analysis
• Export/Import - CSV, Excel, PDF export
• Webhook support - Real-time change notifications

🔒 Security & Privacy

• No data storage: This server doesn't store your spreadsheet data
• Credential security: Uses Google's official authentication libraries
• Minimal permissions: Requests only necessary API scopes
• Local processing: All operations performed locally
• Audit trail: All API calls logged for debugging

See SECURITY.md for detailed security information.

📊 Comparison with Other Solutions

Feature	This MCP Server	Google Sheets API	Other MCP Servers
Spreadsheet Discovery	✅ Full Drive integration	❌ Requires sheet IDs	❌ Limited or none
Claude CLI Optimized	✅ Purpose-built	❌ Generic API	⚠️ Basic integration
Slash Commands	✅ 8 commands included	❌ None	❌ None
Authentication Options	✅ Multiple methods	✅ Standard OAuth	⚠️ Varies
Error Handling	✅ User-friendly	❌ Technical errors	⚠️ Varies
Interactive Workflows	✅ Guided prompts	❌ None	❌ None

🆘 Troubleshooting

Common Issues

"Authentication failed"

• Run the setup wizard: claude-google-sheets-mcp --setup
• For GCP users: Use gcloud auth application-default login with proper scopes
• Check that Google Sheets and Drive APIs are enabled in your Google Cloud project

"Spreadsheet not found"

• Use /list-sheets to see available spreadsheets
• Check spreadsheet sharing permissions (especially for service accounts)
• Verify the spreadsheet ID is correct

"Invalid range"

• Use A1 notation (e.g., "A1:C10", "Sheet1!A1:C10")
• Check that the range exists in the spreadsheet
• Include sheet name if the spreadsheet has multiple tabs

"Insufficient permissions"

• For Application Default Credentials, ensure you have the right scopes:

  gcloud auth application-default login --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/spreadsheets,https://www.googleapis.com/auth/drive"
  

• For service accounts, ensure the service account email has been granted access to your spreadsheets

Getting Help

1. Check the Issues page
2. Review SLASH_COMMANDS.md for usage examples
3. Enable debug logging: --debug flag
4. Join discussions in the repository

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Anthropic for Claude and the Model Context Protocol
• Google for the Sheets and Drive APIs
• MCP Community for tools and inspiration
• Contributors who help improve this project

📞 Support

• 🐛 Bug Reports: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📖 Documentation: Wiki

---

Made with ❤️ for the Claude and MCP community