mcp-google-sheets

🤔 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
• list_spreadsheets - Find spreadsheets
• list_sheets - Navigate tabs

All Available Tools:

• add_columns
• add_rows
• batch_update
• batch_update_cells
• copy_sheet
• create_sheet
• create_spreadsheet
• find_in_spreadsheet
• get_multiple_sheet_data
• get_multiple_spreadsheet_summary
• get_sheet_data
• get_sheet_formulas
• list_folders
• list_sheets
• list_spreadsheets
• rename_sheet
• search_spreadsheets
• share_spreadsheet
• update_cells

Note: If neither --include-tools nor ENABLED_TOOLS is specified, all tools are enabled (default behavior).

🛠️ Available Tools & Resources

This server exposes the following tools for interacting with Google Sheets:

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

(Input parameters are typically strings unless otherwise specified)

• list_spreadsheets: Lists spreadsheets in the configured Drive folder (Service Account) or accessible by the user (OAuth).
  • folder_id (optional string): Google Drive folder ID to search in. Get from its URL. If omitted, uses the configured default folder or searches 'My Drive'.
  • Returns: List of objects [{id: string, title: string}]
• create_spreadsheet: Creates a new spreadsheet.
  • title (string): The desired title for the spreadsheet. Example: "Quarterly Report Q4".
  • folder_id (optional string): Google Drive folder ID where the spreadsheet should be created. Get from its URL. If omitted, uses configured default or root.
  • Returns: Object with spreadsheet info, including spreadsheetId, title, and folder.
• get_sheet_data: Reads data from a range in a sheet/tab.
  • spreadsheet_id (string): The spreadsheet ID (from its URL).
  • sheet (string): Name of the sheet/tab (e.g., "Sheet1").
  • range (optional string): A1 notation (e.g., 'A1:C10', 'Sheet1!B2:D'). If omitted, reads the whole sheet/tab specified by sheet.
  • include_grid_data (optional boolean, default False): If True, returns full grid data including formatting and metadata (much larger). If False, returns values only (more efficient).
  • Returns: If include_grid_data=True, full grid data with metadata (get response). If False, a values result object from the Values API (values.get response).
• get_sheet_formulas: Reads formulas from a range in a sheet/tab.
  • spreadsheet_id (string): The spreadsheet ID (from its URL).
  • sheet (string): Name of the sheet/tab (e.g., "Sheet1").
  • range (optional string): A1 notation (e.g., 'A1:C10', 'Sheet1!B2:D'). If omitted, reads all formulas in the sheet/tab specified by sheet.
  • Returns: 2D array of cell formulas (array of arrays) (values.get response).
• update_cells: Writes data to a specific range. Overwrites existing data.
  • spreadsheet_id (string): The spreadsheet ID (from its URL).
  • sheet (string): Name of the sheet/tab (e.g., "Sheet1").
  • range (string): A1 notation range to write to (e.g.