mcp-google-sheets

• 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.

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.