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](#-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**](#-google-cloud-platform-setup-detailed) guide below. 2. **🐍 Install `uv`** * `uvx` is part of `uv`, a fast Python package installer and resolver. Install it if you haven't already: ```bash # 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)** ```bash # 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)** ```cmd set SERVICE_ACCOUNT_PATH="C:\path o\your\service-account-key.json" set DRIVE_FOLDER_ID="YOUR_DRIVE_FOLDER_ID" ``` * **(Windows PowerShell)** ```powershell $env:SERVICE_ACCOUNT_PATH = "C:\path o\your\service-account-key.json" $env:DRIVE_FOLDER_ID = "YOUR_DRIVE_FOLDER_ID" ``` * ➡️ See [**Detailed Authentication & Environment Variables**](#-authentication--environment-variables-detailed) for other options (OAuth, `CREDENTIALS_CONFIG`). 4. **🏃 Run the Server!** * `uvx` will automatically download and run the latest version of `mcp-google-sheets`: ```bash 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**](#-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**](#-tool-filtering-reduce-context-usage) 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`: ```json { "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`: ```json { "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](#-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](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/get#response-body)). If `False`, a values result object from the Values API ([`values.get` response](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets.values/get#response-body)). * **`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](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets.values/get#response-body)). * **`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. ---