Claude Google Sheets MCP Server

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:

Clone the repository:

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

Install the server:
```
./install.sh
```

Run the interactive setup wizard:

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

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"
      ]
    }
  }
}

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

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes
Add tests for new functionality
Run the test suite: python test_server.py
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
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

Check the Issues page
Review SLASH_COMMANDS.md for usage examples
Enable debug logging: --debug flag
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

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.github		.github
examples		examples
slash-commands		slash-commands
src/claude_google_sheets		src/claude_google_sheets
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
SLASH_COMMANDS.md		SLASH_COMMANDS.md
install-claude-cli.sh		install-claude-cli.sh
install-slash-commands.sh		install-slash-commands.sh
install-windows.ps1		install-windows.ps1
install.sh		install.sh
pyproject.toml		pyproject.toml
test_server.py		test_server.py

License

ringo380/claude-google-sheets-mcp

Folders and files

Latest commit

History

Repository files navigation