mcp-google-sheets

mcp-google-sheets

<i>Your AI Assistant's Gateway to Google Sheets! </i>📊

---

🤔 What is this?

mcp-google-sheets is a Python-based MCP server that acts as a bridge between any MCP-compatible client (like Claude Desktop) and the Google Sheets API. It allows you to interact with your Google Spreadsheets using a defined set of tools, enabling powerful automation and data manipulation workflows driven by AI.

---

🚀 Quick Start (Using uvx)

Essentially the server runs in one line: uvx mcp-google-sheets@latest.

This command will automatically download the latest code and run it. We recommend always using @latest to ensure you have the newest version with the latest features and bug fixes.

Refer to the ID Reference Guide for more information about the IDs used below.

1. ☁️ Prerequisite: Google Cloud Setup

   • You must configure Google Cloud Platform credentials and enable the necessary APIs first. We strongly recommend using a Service Account.
   • ➡️ Jump to the Detailed Google Cloud Platform Setup guide below.

2. 🐍 Install uv

   • uvx is part of uv, a fast Python package installer and resolver. Install it if you haven't already:

     # macOS / Linux
     curl -LsSf https://astral.sh/uv/install.sh | sh
     # Windows
     powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
     # Or using pip:
     # pip install uv
     

     Follow instructions in the installer output to add uv to your PATH if needed.

3. 🔑 Set Essential Environment Variables (Service Account Recommended)

   • You need to tell the server how to authenticate. Set these variables in your terminal:
   • (Linux/macOS)

     # Replace with YOUR actual path and folder ID from the Google Setup step
     export SERVICE_ACCOUNT_PATH="/path/to/your/service-account-key.json"
     export DRIVE_FOLDER_ID="YOUR_DRIVE_FOLDER_ID"
     

   • (Windows CMD)

     set SERVICE_ACCOUNT_PATH="C:\path\to\your\service-account-key.json"
     set DRIVE_FOLDER_ID="YOUR_DRIVE_FOLDER_ID"
     

   • (Windows PowerShell)

     $env:SERVICE_ACCOUNT_PATH = "C:\path\to\your\service-account-key.json"
     $env:DRIVE_FOLDER_ID = "YOUR_DRIVE_FOLDER_ID"
     

   • ➡️ See Detailed Authentication & Environment Variables for other options (OAuth, CREDENTIALS_CONFIG).

4. 🏃 Run the Server!

   • uvx will automatically download and run the latest version of mcp-google-sheets:

     uvx mcp-google-sheets@latest
     

   • The server will start and print logs indicating it's ready.

   • 💡 Pro Tip: Always use @latest to ensure you get the newest version with bug fixes and features. Without @latest, uvx may use a cached older version.

5. 🔌 Connect your MCP Client

   • Configure your client (e.g., Claude Desktop) to connect to the running server.
   • Depending on the client you use, you might not need step 4 because the client can launch the server for you. But it's a good practice to test run step 4 anyway to make sure things are set up properly.
   • ➡️ See Usage with Claude Desktop for examples.

6. ⚡ Optional: Enable Tool Filtering (Reduce Context Usage)

   • By default, all 19 tools are enabled (~13K tokens). To reduce context usage, enable only the tools you need.
   • ➡️ See Tool Filtering for details.

You're ready! Start issuing commands via your MCP client.

---

✨ Key Features

• Seamless Integration: Connects directly to Google Drive & Google Sheets APIs.
• Comprehensive Tools: Offers a wide range of operations (CRUD, listing, batching, sharing, formatting, etc.).
• Flexible Authentication: Supports Service Accounts (recommended), OAuth 2.0, and direct credential injection via environment variables.
• Easy Deployment: Run instantly with uvx (zero-install feel) or clone for development using uv.
• AI-Ready: Designed for use with MCP-compatible clients, enabling natural language spreadsheet interaction.
• Tool Filtering: Reduce context window usage by enabling only the tools you need with --include-tools or ENABLED_TOOLS environment variable.

---

🎯 Tool Filtering (Reduce Context Usage)

Problem: By default, this MCP server exposes all 19 tools, consuming ~13,000 tokens before any conversation begins. If you only need a few tools, this wastes valuable context window space.

Solution: Use tool filtering to enable only the tools you actually use.

How to Enable Tool Filtering

You can filter tools using either:

1. Command-line argument --include-tools:

   {
     "mcpServers": {
       "google-sheets": {
         "command": "uvx",
         "args": [
           "mcp-google-sheets@latest",
           "--include-tools",
           "get_sheet_data,update_cells,list_spreadsheets,list_sheets"
         ],
         "env": {
           "SERVICE_ACCOUNT_PATH": "/path/to/credentials.json"
         }
       }
     }
   }
   

2. Environment variable ENABLED_TOOLS:

   {
     "mcpServers": {
       "google-sheets": {
         "command": "uvx",
         "args": ["mcp-google-sheets@latest"],
         "env": {
           "SERVICE_ACCOUNT_PATH": "/path/to/credentials.json",
           "ENABLED_TOOLS": "get_sheet_data,update_cells,list_spreadsheets,list_sheets"
         }
       }
     }
   }
   

Available Tool Names

When filtering, use these exact tool names (comma-separated, no spaces):

Most Common Tools (recommended subset):

• get_sheet_data - Read from spreadsheets
• update_cells - Write to spreadsheets
• `li