xing5/mcp-google-sheets

Your AI Assistant's Gateway to 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:
*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)**
* **(Windows CMD)**
* **(Windows PowerShell)**
* ➡️ 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:
* 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:
2. **Environment variable** ENABLED_TOOLS:
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).