# MCP Google表格服务器
## 基本信息
- Slug: `xing5-mcp-google-sheets`
- Source: modelscope
- Publisher: @xing5/mcp-google-sheets
- Categories: cloud-storage / databases
- Hosted: No
- License: MIT License
- Source URL: https://www.modelscope.cn/mcp/servers/@xing5/mcp-google-sheets
## 简介
一种集成了Google Drive和Google Sheets的模型上下文协议服务器，允许用户通过自然语言命令创建、读取、更新和管理电子表格。
## 安装提示

```bash
# macOS / Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Windows powershell -c "irm https://astral.sh/uv/install.ps1 | iex" # 或者使用 pip: # pip install uv
```

## MCP Server 详情

<div align="center">
  <!-- 主标题链接 -->
  <b>mcp-google-sheets</b>

  <!-- 描述段落 -->
  <p align="center">
    <i>您的AI助手通往Google Sheets的门户！</i>📊
  </p>

[![PyPI - Version](https://img.shields.io/pypi/v/mcp-google-sheets)](https://pypi.org/project/mcp-google-sheets/)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/mcp-google-sheets)](https://pypi.org/project/mcp-google-sheets/)
![GitHub License](https://img.shields.io/github/license/xing5/mcp-google-sheets)
![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/xing5/mcp-google-sheets/release.yml)
</div>

---

## 🤔 这是什么？

`mcp-google-sheets` 是一个基于Python的MCP服务器，它充当任何MCP兼容客户端（如Claude Desktop）与Google Sheets API之间的桥梁。它允许您使用一组定义好的工具与您的Google电子表格进行交互，从而实现由AI驱动的强大自动化和数据处理工作流。

## 🚀 快速开始（使用 `uvx`）

基本上，服务器运行只需一行命令：`uvx mcp-google-sheets`。

此命令会根据需要自动下载最新代码并运行。但是，设置Google Cloud需要一些步骤，请阅读以下步骤。

1.  **☁️ 前提条件：Google Cloud 设置**
    *   您**必须**先配置 Google Cloud Platform 凭证并启用必要的 API。我们强烈建议使用**服务账号**。
    *   ➡️ 跳转至下方的 [**详细的 Google Cloud Platform 设置**](#-google-cloud-platform-setup-detailed) 指南。

2.  **🐍 安装 `uv`**
    *   `uvx` 是 `uv` 的一部分，`uv` 是一个快速的 Python 包安装器和解析器。如果您尚未安装，请执行以下操作：
        ```bash
        # macOS / Linux
        curl -LsSf https://astral.sh/uv/install.sh | sh
        # Windows
        powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
        # 或者使用 pip:
        # pip install uv
        ```
        *如果需要，请按照安装程序输出中的说明将 `uv` 添加到您的 PATH 中。*

3.  **🔑 设置必需的环境变量（推荐使用服务账号）**
    *   您需要告诉服务器如何进行身份验证。在终端中设置这些变量：
    *   **(Linux/macOS)**
        ```bash
        # 请用您从 Google 设置步骤中获得的实际路径和文件夹 ID 替换
        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"
        ```
    *   ➡️ 查看 [**详细的身份验证和环境变量**](#-authentication--environment-variables-detailed) 获取其他选项（OAuth, `CREDENTIALS_CONFIG`）。

4.  **🏃 运行服务器！**
    *   `uvx` 将自动下载并运行最新版本的 `mcp-google-sheets`：
        ```bash
        uvx mcp-google-sheets
        ```
    *   服务器将启动，并打印日志表明已准备好。

5.  **🔌 连接您的 MCP 客户端**
    *   配置您的客户端（例如 Claude Desktop），以连接到正在运行的服务器。
    *   根据您使用的客户端不同，您可能不需要执行第 4 步，因为客户端可以为您启动服务器。但无论如何测试运行第 4 步是一个好习惯，以确保一切设置正确。
    *   ➡️ 查看 [**与 Claude Desktop 一起使用**](#-usage-with-claude-desktop) 获取示例。

您已经准备好了！开始通过您的 MCP 客户端发出命令吧。

---

## ✨ 主要功能

*   **无缝集成：** 直接连接到 Google Drive 和 Google Sheets API。
*   **全面的工具：** 提供广泛的操作（CRUD、列表、批处理、共享、格式化等）。
*   **灵活的身份验证：** 支持 **服务帐户（推荐）**、OAuth 2.0 以及通过环境变量直接注入凭证。
*   **轻松部署：** 使用 `uvx` 即刻运行（零安装体验），或使用 `uv` 克隆以进行开发。
*   **AI 就绪：** 专为与 MCP 兼容的客户端一起使用而设计，支持自然语言电子表格交互。

---

## 🛠️ 可用工具和资源

此服务器提供了以下工具来与 Google Sheets 进行交互：

*(输入参数通常是字符串，除非另有说明)*

*   **`list_spreadsheets`**: Lists spreadsheets in the configured Drive folder (Service Account) or accessible by the user (OAuth).
    *   _Returns:_ List of objects `[{id: string, title: string}]`
*   **`create_spreadsheet`**: Creates a new spreadsheet.
    *   `title` (string): The desired title.
    *   _Returns:_ Object with spreadsheet info, including `spreadsheetId`.
*   **`get_sheet_data`**: Reads data from a range in a sheet.
    *   `spreadsheet_id` (string)
    *   `sheet` (string): Name of the sheet.
    *   `range` (optional string): A1 notation (e.g., `'A1:C10'`, `'Sheet1!B2:D'`). If omitted, reads the whole sheet.
    *   _Returns:_ 2D array of cell values.
*   **`update_cells`**: Writes data to a specific range. Overwrites existing data.
    *   `spreadsheet_id` (string)
    *   `sheet` (string)
    *   `range` (string): A1 notation.
    *   `data` (2D array): Values to write.
    *   _Returns:_ Update result object.
*   **`batch_update_cells`**: Updates multiple ranges in one API call.
    *   `spreadsheet_id` (string)
    *   `sheet` (string)
    *   `ranges` (object): Dictionary mapping range strings (A1 notation) to 2D arrays of values `{ "A1:B2": [[1, 2], [3, 4]], "D5": [["Hello"]] }`.
    *   _Returns:_ Batch update result object.
*   **`add_rows`**: Appends rows to the end of a sheet (after the last row with data).
    *   `spreadsheet_id` (string)
    *   `sheet` (string)
    *   `data` (2D array): Rows to append.
    *   _Returns:_ Update result object.
*   **`list_sheets`**: Lists all sheet names within a spreadsheet.
    *   `spreadsheet_id` (string)
    *   _Returns:_ List of sheet name strings `["Sheet1", "Sheet2"]`.
*   **`create_sheet`**: Adds a new sheet (tab) to a spreadsheet.
    *   `spreadsheet_id` (string)
    *   `title` (string): Name for the new sheet.
    *   _Returns:_ New sheet properties object.
*   **`get_multiple_sheet_data`**: Fetches data from multiple ranges across potentially different spreadsheets in one call.
    *   `queries` (array of objects): Each object needs `spreadsheet_id`, `sheet`, and `range`. `[{spreadsheet_id: 'abc', sheet: 'Sheet1', range: 'A1:B2'}, ...]`.
    *   _Returns:_ List of objects, each containing the query params and fetched `data` or an `error`.
*   **`get_multiple_spreadsheet_summary`**: Gets titles, sheet names, headers, and first few rows for multiple spreadsheets.
    *   `spreadsheet_ids` (array of strings)
    *   `rows_to_fetch` (optional integer, default 5): How many rows (including header) to preview.
    *   _Returns:_ List of summary objects for each spreadsheet.
*   **`share_spreadsheet`**: Shares a spreadsheet with specified users/emails and roles.
    *   `spreadsheet_id` (string)
    *   `recipients` (array of objects): `[{email_address: 'user@example.com', role: 'writer'}, ...]`. Roles: `reader`, `commenter`, `writer`.
    *   `send_notification` (optional boolean, default True): Send email notifications.
    *   _Retur…