mcp-google-sheets

🤔 这是什么？

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 云平台设置指南。
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" # Or using pip: # pip install uv
     如果需要，请按照安装程序输出中的说明将uv添加到您的 PATH 中。
3. 🔑 设置必要的环境变量（建议使用服务帐户）
   • 您需要告诉服务器如何进行身份验证。在终端中设置以下变量：
   • （Linux/macOS）
     # 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 命令）
     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-Ready：**专为与 MCP 兼容的客户端一起使用而设计，可实现自然语言电子表格交互。

🛠️ 可用的工具和资源

该服务器公开了以下与 Google 表格交互的工具：

（除非另有说明，输入参数通常是字符串）

• list_spreadsheets ：列出配置的 Drive 文件夹（服务帐户）中或用户可访问的电子表格（OAuth）。
  • *返回：*对象列表[{id: string, title: string}]
• create_spreadsheet ：创建一个新的电子表格。
  • title （字符串）：所需的标题。
  • *返回：*包含电子表格信息的对象，包括spreadsheetId 。
• get_sheet_data ：从工作表的某个范围内读取数据。
  • spreadsheet_id （字符串）
  • sheet （字符串）：工作表的名称。
  • range （可选字符串）：A1 格式（例如， 'A1:C10' ， 'Sheet1!B2:D' ）。如果省略，则读取整个 Sheet。
  • *返回：*单元格值的二维数组。
• update_cells ：将数据写入特定范围。覆盖现有数据。
  • spreadsheet_id （字符串）
  • sheet （字符串）
  • range （字符串）：A1 符号。
  • data （二维数组）：要写入的值。
  • *返回：*更新结果对象。
• batch_update_cells ：在一次 API 调用中更新多个范围。
  • spreadsheet_id （字符串）
  • sheet （字符串）
  • ranges （对象）：将范围字符串（A1 符号）映射到二维值数组{ "A1:B2": [[1, 2], [3, 4]], "D5": [["Hello"]] } 。
  • *返回：*批量更新结果对象。
• add_rows ：将行附加到工作表的末尾（在最后一行数据之后）。
  • spreadsheet_id （字符串）
  • sheet （字符串）
  • data （二维数组）：要附加的行。
  • *返回：*更新结果对象。
• list_sheets ：列出电子表格中的所有工作表名称。
  • spreadsheet_id （字符串）
  • *返回：*工作表名称字符串列表["Sheet1", "Sheet2"] 。
• create_sheet ：向电子表格添加新工作表（选项卡）。
  • spreadsheet_id （字符串）
  • title （字符串）：新工作表的名称。
  • *返回：*新的工作表属性对象。
• get_multiple_sheet_data ：一次调用即可从可能不同的电子表格的多个范围中获取数据。
  • queries （对象数组）：每个对象都需要spreadsheet_id 、 sheet和range 。 [{spreadsheet_id: 'abc', sheet: 'Sheet1', range: 'A1:B2'}, ...] 。
  • *返回：*对象列表，每个对象包含查询参数和获取的data或error 。
• get_multiple_spreadsheet_summary ：获取多个电子表格的标题、工作表名称、标题和前几行。
  • spreadsheet_ids （字符串数组）
  • rows_to_fetch （可选整数，默认值为 5）：要预览多少行（包括标题）。
  • *返回：*每个电子表格的摘要对象列表。
• share_spreadsheet ：与指定的用户/电子邮件和角色共享电子表格。
  • spreadsheet_id （字符串）
  • recipients （对象数组）： [{email_address: 'user@example.com', role: 'writer'}, ...] 。角色： reader ， commenter ， writer 。
  • send_notification （可选布尔值，默认 True）：发送电子邮件通知。
  • *返回：*包含successes和failures列表的字典。
• add_columns ：向工作表添加列。 （如果已实现，请验证参数）
• copy_sheet ：复制电子表格中的工作表。 （如果已实现，请验证参数）
• rename_sheet ：重命名现有工作表。 （如果已实现，请验证参数）

MCP 资源：

• spreadsheet://{spreadsheet_id}/info ：获取有关 Google 电子表格的基本元数据。
  • *返回：*包含电子表格信息的 JSON 字符串。

☁️ Google 云平台设置（详细）

运行服务器之前需要进行此设置。

1. **创建/选择 GCP 项目：**转到Google Cloud Console 。
2. **启用 API：**前往“API 和服务”->“库”。搜索并启用：
   • Google Sheets API
   • Google Drive API
3. **配置凭据：**您需要选择以下一种身份验证方法（建议使用服务帐户）。

🔑 身份验证和环境变量（详细）

服务器需要凭据才能访问 Google API。请选择一种方法：

方法 A：服务帐户（推荐用于服务器/自动化）✅

• **为什么？**无头（无需浏览器）、安全，非常适合服务器环境。而且不会轻易过期。
• 步骤：
  1. **创建服务帐户：**在 GCP 控制台 -> “IAM 和管理” -> “服务帐户”。
     • 点击“+ 创建服务帐户”。为其命名（例如， mcp-sheets-service ）。
     • 授予角色：添加Editor角色以获得广泛访问权限，或添加更细粒度的角色（如roles/drive.file和特定的 Sheets 角色）以获得更严格的权限。
     • 点击“完成”。找到该账户，点击“操作”(⋮) -> “管理密钥”。
     • 点击“添加密钥”->“创建新密钥”-> JSON ->“创建”。
     • 下载并安全存储JSON 密钥文件。
  2. 创建并共享 Google Drive 文件夹：
     • 在Google Drive中，创建一个文件夹（例如“AI Managed Sheets”）。
     • 记下 URL 中的文件夹 ID ： https://drive.google.com/drive/folders/THIS_IS_THE_FOLDER_ID 。
     • 右键点击文件夹->“共享”->“共享”。
     • 输入服务帐户的电子邮件（来自 JSON 文件client_email ）。
     • 授予编辑权限。取消勾选“通知他人”。点击“共享”。
  3. 设置环境变量：
     • SERVICE_ACCOUNT_PATH ：下载的 JSON 密钥文件的完整路径。
     • DRIVE_FOLDER_ID ：共享 Google Drive 文件夹的 ID。 （请参阅“超级快速入门”查看特定于操作系统的示例）

方法 B：OAuth 2.0（交互式/个人使用）🧑‍💻

• **为什么？**因为对于个人使用或本地开发来说，交互式浏览器登录是可以的。
• 步骤：
  1. **配置 OAuth 授权界面：**在 GCP Console -> “API 和服务” -> “OAuth 授权界面” 中选择“外部”，填写所需信息，添加授权范围（ .../auth/spreadsheets ， .../auth/drive ），并根据需要添加测试用户。
  2. **创建 OAuth 客户端 ID：**在 GCP Console -> “API 和服务” -> “凭据”。“+ 创建凭据” -> “OAuth 客户端 ID” -> 类型：桌面应用。将其命名为“CREATE”。下载 JSON 文件。
  3. 设置环境变量：
     • CREDENTIALS_PATH ：下载的 OAuth 凭据 JSON 文件的路径（默认值： credentials.json ）。
     • TOKEN_PATH ：用户首次登录后存储刷新令牌的路径（默认值： token.json ）。必须可写。

方法 C：直接凭证注入（高级）🔒

• **为什么？**在 Docker、Kubernetes 或 CI/CD 等环境中很有用，因为这些环境中文件管理比较困难，但环境变量却很容易/安全。避免访问文件系统。
• **怎么做呢？**您无需提供凭证文件的路径，而是直接在环境变量中提供以 Base64 编码的文件内容。
• 步骤：
  1. 获取您的凭证 JSON 文件（服务帐户密钥或 OAuth 客户端 ID 文件）。我们将其命名为your_credentials.json 。
  2. 生成Base64字符串：
     • （Linux/macOS）： base64 -w 0 your_credentials.json
     • （Windows PowerShell）：
       $filePath = "C:\path\to\your_credentials.json"; # Use actual path $bytes = [System.IO.File]::ReadAllBytes($filePath); $base64 = [System.Convert]::ToBase64String($bytes); $base64 # Copy this output
     • **（警告）：**避免将敏感凭证粘贴到不受信任的在线编码器中。
  3. 设置环境变量：
     • CREDENTIALS_CONFIG ：将此变量设置为您刚刚生成的完整 Base64 字符串。
       # Example (Linux/macOS) - Use the actual string generated export CREDENTIALS_CONFIG="ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb..."

身份验证优先级和摘要

服务器按以下顺序检查凭证：

1. CREDENTIALS_CONFIG （Base64 内容）
2. SERVICE_ACCOUNT_PATH （服务帐户 JSON 的路径）
3. CREDENTIALS_PATH （OAuth JSON 路径）- 如果令牌丢失或过期，则触发交互流程。

环境变量摘要：

⚙️ 运行服务器（详细）

方法一：使用uvx （推荐用户）

如超级快速入门中所示，这是最简单的方法。设置环境变量，然后运行：

uvx临时处理获取和运行包。

方法 2：用于开发（克隆 Repo）

如果要修改代码：

1. 克隆： git clone https://github.com/yourusername/mcp-google-sheets.git && cd mcp-google-sheets （使用实际 URL）
2. **设置环境变量：**如上所述。
3. **使用uv运行：（**使用本地代码）
   uv run mcp-google-sheets # Or via the script name if defined in pyproject.toml, e.g.: # uv run start

🔌 与 Claude Desktop 一起使用

将服务器配置添加到mcpServers下的claude_desktop_config.json中。选择与你的设置匹配的块：

（首次使用时，浏览器可能会打开 Google 登录）

💬 Claude 的示例提示

连接后，尝试如下提示：

• “列出我有权访问的所有电子表格。”（或“在我的 AI 管理表格文件夹中”）
• “创建一个名为‘2024 年第三季度季度销售报告’的新电子表格。”
• “在‘季度销售报告’电子表格中，获取 Sheet1 范围 A1 至 E10 中的数据。”
• “向 ID 为1aBcDeFgHiJkLmNoPqRsTuVwXyZ电子表格中添加一个名为‘Summary’的新工作表。”
• “在我的‘项目任务’电子表格的‘任务’表中，将单元格 B2 更新为‘进行中’。”
• “将这些行附加到电子表格XYZ中的‘日志’表： [['2024-07-31', 'Task A Completed'], ['2024-08-01', 'Task B Started']] ”
• “获取电子表格‘销售数据’和‘库存数量’的摘要。”
• 将‘团队休假计划’电子表格分享给team@example.com （读者）和manager@example.com （撰写者）。不发送通知。

🤝 贡献

欢迎贡献！请提交问题来讨论错误或功能请求。欢迎提交拉取请求。

📄 许可证

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅LICENSE文件。

🙏 致谢

• 使用FastMCP构建。
• 受到kazz187/mcp-google-spreadsheet的启发。
• 使用 Google API Python 客户端库。