Google Sheets MCP Server

A Model Context Protocol (MCP) server that provides tools for reading and interacting with Google Sheets data. This server enables AI assistants like Claude Desktop to seamlessly access, search, and analyze Google Spreadsheets.

Built with uv for fast and reliable dependency management.

🚀 Features

• 📋 List Spreadsheets: Discover all accessible Google Spreadsheets

• 🔍 Search by Name: Find spreadsheets by name (exact or partial match)

• 📊 Read Sheet Data: Extract data from specific ranges or entire sheets

• 📝 Sheet Metadata: Get detailed information about spreadsheet structure

• 📑 List Sheets/Tabs: View all sheets within a spreadsheet

• 🔎 Search Content: Find specific data within sheets

• 🎯 Range Data: Get formatted data from specific cell ranges

• 🔐 Dual Authentication: Supports both OAuth 2.0 (private sheets) and API key (public sheets)

📦 Installation

Prerequisites

• Python 3.8+

• uv package manager

• Google Cloud Project with Sheets API enabled

• Claude Desktop or other MCP-compatible client

Dependencies

This project uses uv for fast and reliable dependency management:

Note: All dependencies are managed through pyproject.toml and uv.lock files.

⚙️ Setup

Option 1: OAuth 2.0 Authentication (Recommended for Private Sheets)

1. Create Google Cloud Project:

   • Go to Google Cloud Console

   • Create a new project or select existing one

   • Enable Google Sheets API and Google Drive API

2. Create OAuth 2.0 Credentials:

   • Go to "Credentials" → "Create Credentials" → "OAuth 2.0 Client ID"

   • Choose "Desktop application"

   • Download the credentials.json file

   • Place it in the project root directory

3. Generate Authentication Token:

   # Run the token generation script using uv uv run token_gen.py

   • A browser window will open for Google authentication

   • Grant necessary permissions

   • This will create token.json file for future use

4. Environment Setup (Optional):

   # Create .env file if you want to use API key fallback echo "SHEET_API_KEY=your_api_key_here" > .env

Option 2: API Key Authentication (Public Sheets Only)

1. Create API Key:

   • Go to Google Cloud Console

   • Enable Google Sheets API

   • Go to "Credentials" → "Create Credentials" → "API Key"

   • Copy the API key

2. Environment Configuration:

   # Create .env file echo "SHEET_API_KEY=your_api_key_here" > .env

Note: API key authentication only works with publicly shared spreadsheets.

🏃‍♂️ Running the Server

Prerequisites

Important: You must generate the authentication token before adding the MCP server to Claude Desktop.

1. Generate Token First:

   uv run token_gen.py

   Complete the OAuth flow in your browser.

2. Then Run Server:

Standalone Mode

With Claude Desktop

Only after completing token generation, add to your Claude Desktop configuration:

Replace

🛠️ Available Tools

1. List Spreadsheets

Lists all Google Spreadsheets accessible to the authenticated user.

2. Search Spreadsheets by Name

Find spreadsheets by name with exact or partial matching.

3. Read Sheet Data

Extract data from a specific range or entire sheet.

4. Get Sheet Metadata

Retrieve detailed information about a spreadsheet.

5. List Sheets

Get all sheet/tab names within a spreadsheet.

6. Search Sheet Data

Find specific content within a sheet.

7. Get Range Data

Extract data with specific formatting options.

🔐 Authentication Scopes

The server uses these Google API scopes:

• https://www.googleapis.com/auth/spreadsheets.readonly - Read spreadsheet content

• https://www.googleapis.com/auth/drive.metadata.readonly - List and discover spreadsheets

📁 Project Structure

🔧 Configuration

Environment Variables

Create a .env file with:

Note: The .env file is optional. OAuth authentication via token_gen.py is the primary method.

🐛 Troubleshooting

Common Issues

1. OAuth Browser Doesn't Open:

   • Check firewall settings

   • Ensure Python has internet access

   • Try running authentication manually first

2. Permission Denied Errors:

   • Verify spreadsheet is accessible with your Google account

   • Check if spreadsheet is shared appropriately

   • Ensure correct API scopes are enabled

3. API Key Limitations:

   • API keys only work with public spreadsheets

   • Use OAuth 2.0 for private spreadsheets

   • Verify spreadsheet sharing settings

4. Token Expiration:

   • Delete token.json to force re-authentication

   • Run uv run token_gen.py again to regenerate

   • Check if refresh token is still valid

5. uv Installation Issues:

   • Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh (Unix) or powershell -c "irm https://astral.sh/uv/install.ps1 | iex" (Windows)

   • Or use pip: pip install uv

   • Verify installation: uv --version

Pre-Authentication

Recommended workflow to avoid OAuth interruption during use:

This ensures authentication is completed before Claude Desktop tries to use the server.

📋 Example Usage with Claude

🤝 Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests if applicable

5. Submit a pull request

📄 License

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

🔗 Related Links

• Model Context Protocol (MCP)

• Google Sheets API Documentation

• Google Drive API Documentation

• Claude Desktop

⚠️ Security Notes

• Keep your credentials.json and token.json files secure

• Never commit authentication files to version control

• Use environment variables for API keys

• Regularly review and rotate credentials

• Follow the principle of least privilege for API scopes