mcp-google-sheets

<div align="center"> <!-- Main Title Link --> <b>mcp-google-sheets</b> <!-- Description Paragraph --> <p align="center"> <i>Your AI Assistant's Gateway to Google Sheets! </i>📊 </p> [](https://pypi.org/project/mcp-google-sheets/) [](https://pepy.tech/projects/mcp-google-sheets)   </div> --- ## 🤔 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\to\your\service-account-key.json" set DRIVE_FOLDER_ID="YOUR_DRIVE_FOLDER_ID" ``` * **(Windows PowerShell)** ```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**](#-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. 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. --- ## 🛠️ 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`**: