Google Sheets MCP Server

🚀 Google Sheets MCP Server

A Model Context Protocol (MCP) server designed for Google Sheets, enabling Claude Desktop to interact directly with Google Sheets. This server provides tools for creating, reading, writing, and managing Google Sheets.

🚀 Quick Start

This Google Sheets MCP server allows Claude Desktop to interact directly with Google Sheets, providing a series of tools for table management.

✨ Features

• Create new Google Sheets.
• Read and write data to existing sheets.
• Format cells and ranges.
• Add and delete sheets.
• Write formulas.
• Search for sheets.
• List available sheets.

📦 Installation

Prerequisites

• Python 3.10 or higher.
• A Google Cloud project with the Google Sheets API enabled.
• OAuth 2.0 credentials from the Google Cloud Console.
• The Claude Desktop application.
• The uv package manager (recommended).

Steps

1. Clone the repository:

git clone https://github.com/yourusername/google-sheets-mcp-server.git
cd google-sheets-mcp-server

2. Create and activate a virtual environment:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install dependencies using uv:

uv pip install -e .

4. Set up Google Cloud credentials:
   • Visit Google Cloud Console.
   • Create a new project or select an existing one.
   • Enable the Google Sheets API and Google Drive API.
   • Create OAuth 2.0 credentials (desktop app).
   • Download the credentials and save them as ~/.config/google_sheets_mcp/google-sheets-mcp.json.

📚 Documentation

Configuration

1. Configure Claude Desktop:
   • Open the Claude Desktop settings.
   • Add the following to claude_desktop_config.json:

{
  "mcpServers": {
    "google_sheets": {
      "command": "/path/to/your/.venv/bin/python",
      "args": [
        "/path/to/your/google_sheets.py",
        "--credentials-path",
        "/Users/yourusername/.config/google_sheets_mcp/google-sheets-mcp.json",
        "--log-level",
        "DEBUG"
      ]
    }
  }
}

2. First-time setup:
   • Manually run the server to complete OAuth authentication:

python google_sheets.py --credentials-path ~/.config/google_sheets_mcp/google-sheets-mcp.json

• Authorize the application according to the browser prompts.
• The token will be automatically saved for future use.

Usage

After setup, you can use the following commands in Claude Desktop:

• Create a new sheet: create_sheet(title: str)
• Format cells: format_range(file_id: str, range: str, format: dict)
• Write a formula: write_formula(file_id: str, range: str, formula: str)
• Add a sheet: add_sheet(file_id: str, title: str)
• Delete a sheet: delete_sheet(file_id: str, sheet_id: int)
• Get sheet properties: get_sheet_properties(file_id: str)

Development

Project Structure

google-sheets-mcp-server/
├── .venv/                  # Virtual environment
├── google_sheets.py        # Main server implementation
├── pyproject.toml         # Project configuration and dependencies
├── tests/                 # Test files
└── README.md             # This file

Adding New Features

1. Add new tool methods to the GoogleSheetsMCP class.
2. Decorate them with @mcp.tool().
3. Update the documentation in the README for the new features.

Running Tests

pytest

Troubleshooting

1. Server connection issues
   • Check if the server is running.
   • Verify the correct path for the credentials.
   • Check the Claude Desktop logs.
2. Authentication issues
   • Ensure the OAuth 2.0 credentials are valid.
   • Check if the application has the correct permissions.
   • Confirm that you are using the latest versions of the libraries and tools.
3. Other issues
   • Check the console output for detailed error information.
   • Ensure the Google Sheets API is correctly enabled.
   • Verify that all dependencies are installed.

💻 Usage Examples

Basic Usage

# This is a simple example demonstrating basic operations using the google_sheets.py library.

from google_sheets import GoogleSheetsMCP

# Initialize the MCP server
mcp = GoogleSheetsMCP(credentials_path='path/to/google-sheets-mcp.json')

# Create a new sheet
sheet_id = mcp.create_sheet('Example Sheet')

# Write data to the sheet
mcp.write_formula(sheet_id, 'A1', '=SUM(1,2)')

# Read cell content
value = mcp.read_cell(sheet_id, 'A1')
print(value)  # Output: 3

# Delete the sheet
mcp.delete_sheet(sheet_id)

FAQ

Q: How to handle OAuth authentication errors? A: Ensure that your Google Cloud project has the correct APIs enabled and the credentials file path is correct. Check the console output for specific error information.

Q: Unable to connect to Google Sheets? A: Confirm that your internet connection is working, the Google Sheets API is enabled, and the credentials in use have appropriate permissions.

Contact

For help or to report issues, visit the project homepage or send an email to support@yourdomain.com.