MCP Google表格服务器

<div align="center"> <!-- 主标题链接 --> <b>mcp-google-sheets</b> <!-- 描述段落 --> <p align="center"> <i>您的AI助手通往Google Sheets的门户！</i>📊 </p>

</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 设置 指南。

2. 🐍 安装 uv

   • uvx 是 uv 的一部分，uv 是一个快速的 Python 包安装器和解析器。如果您尚未安装，请执行以下操作：

     # 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)

     # 请用您从 Google 设置步骤中获得的实际路径和文件夹 ID 替换
     export SERVICE_ACCOUNT_PATH="/path/to/your/service-account-key.json"
     export DRIVE_FOLDER_ID="YOUR_DRIVE_FOLDER_ID"
     

   • (Windows CMD)

     set SERVICE_ACCOUNT_PATH="C:\path\to\your\service-account-key.json"
     set DRIVE_FOLDER_ID="YOUR_DRIVE_FOLDER_ID"
     

   • (Windows PowerShell)

     $env:SERVICE_ACCOUNT_PATH = "C:\path\to\your\service-account-key.json"
     $env:DRIVE_FOLDER_ID = "YOUR_DRIVE_FOLDER_ID"
     

   • ➡️ 查看 详细的身份验证和环境变量 获取其他选项（OAuth, CREDENTIALS_CONFIG）。

4. 🏃 运行服务器！

   • uvx 将自动下载并运行最新版本的 mcp-google-sheets：

     uvx mcp-google-sheets
     

   • 服务器将启动，并打印日志表明已准备好。

5. 🔌 连接您的 MCP 客户端

   • 配置您的客户端（例如 Claude Desktop），以连接到正在运行的服务器。
   • 根据您使用的客户端不同，您可能不需要执行第 4 步，因为客户端可以为您启动服务器。但无论如何测试运行第 4 步是一个好习惯，以确保一切设置正确。
   • ➡️ 查看 与 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…