MCP谷歌表格服务器

【技术文档摘要】

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

</div>

---

🤔 这是什么？

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

🚀 快速开始（使用 uvx）

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

此命令会自动下载最新代码并运行。我们建议始终使用 @latest，以确保您拥有最新版本及其最新的功能和错误修复。

1. ☁️ 前提条件：Google云平台设置

   • 您必须先配置Google云平台凭证并启用必要的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"
     # 或者使用pip：
     # pip install uv
     

     根据安装程序输出中的说明，如有需要，请将 uv 添加到您的PATH中。

3. 🔑 设置必需的环境变量（推荐使用服务账户）

   • 您需要告诉服务器如何进行身份验证。在终端中设置这些变量：
   • (Linux/macOS)

     # 替换为您实际的路径和文件夹ID，从Google设置步骤中获取
     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@latest
     

   • 服务器启动后会打印日志，表明其已准备好。

   • 💡 提示： 始终使用 @latest 以确保您获得具有错误修复和新功能的最新版本。不使用 @latest 时，uvx 可能会使用缓存的旧版本。

5. 🔌 连接您的MCP客户端

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

现在您可以开始通过您的MCP客户端发出命令了。

---

✨ 关键特性

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

---

🛠️ 可用工具及资源

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

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

• list_spreadsheets: 列出配置的云端硬盘文件夹（服务账户）或用户可访问的（OAuth）电子表格。
  • 返回值： 对象列表 [{"id": 字符串, "title": 字符串}]
• create_spreadsheet: 创建新的电子表格。
  • title (字符串): 所需的标题。
  • 返回值： 包含电子表格信息的对象，包括 spreadsheetId。
• get_sheet_data: 从表中的某个范围读取数据。
  • spreadsheet_id (字符串)
  • sheet (字符串): 表的名字。
  • range (可选字符串): A1表示法（例如，'A1:C10', 'Sheet1!B2:D'）。如果省略，则读取整个表。
  • include_grid_data (可选布尔值，默认为False): 如果为True，则包含单元格格式和其他元数据（响应较大）。如果为False，则仅返回值（更高效）。
  • 返回值： 如果 include_grid_data=True，则返回完整的网格数据及元数据。如果为 False，则返回来自Values API的结果对象。
• get_sheet_formulas: 从表中的某个范围读取公式。
  • spreadsheet_id (字符串)
  • sheet (字符串): 表的名字。
  • range (可选字符串): A1表示法（例如，'A1:C1_0', 'Sheet1!B2:D'）。如果省略，则读取整个表。
  • 返回值： 二维数组的单元格公式。
• 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): 发送电子邮件通知。
  • 返回值： 包含成功和失败列表的字典。
• add_columns: 向表中添加列。(如果实现，请验证参数)
• copy_sheet: 在电子表格内复制一个表。(如果实现，请验证参数)
• rename_sheet: 重命名现有的表。(如果实现，请验证参数)

MCP资源：

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

---

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

在运行服务器之前，此设置是必需的。

1. 创建/选择一个GCP项目： 转到Google云控制台。
2. 启用API： 导航至“API和服务” -> “库”。搜索并启用：
   • Google表格API
   • Google云端硬盘API
3. 配置凭证： 您需要选择以下一种身份验证方法之一（推荐使用服务账户）。

---

🔑 认证及环境变量（详细）

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

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

• 为什么？ 无头（无需浏览器），安全，适合服务器环境。不易过期。
• 步骤：
  1. 创建服务账户： 在GCP控制台 -> “身份和管理” -> “服务账户”。
     • 点击“+ 创建服务账户”。命名（例如，mcp-sheets-service）。
     • 授予权限：添加 编辑者 角色以获得广泛访问权限，或者添加更细粒度的角色（如 roles/drive.file 和特定的表格角色）以获得更严格的权限。
     • 点击“完成”。找到该账户，点击操作（⋮）-> “管理密钥”。
     • 点击“添加密钥” -> “创建新密钥” -> JSON -> “创建”。
     • 下载并安全存储 JSON密钥文件。
  2. 创建并共享Google云端硬盘文件夹：
     • 在Google云端硬盘中，创建一个文件夹（例如，“AI管理表格”）。
     • 注意文件夹ID，从URL中获取：https://drive.google.com/drive/folders/THIS_IS_THE_FOLDER_ID。
     • 右键点击文件夹 -> “分享” -> “分享”。
     • 输入服务账户的电子邮件（从JSON文件中的 client_email 获取）。
     • 授予 编辑者 权限。取消选中“发送通知”。点击“分享”。
  3. 设置环境变量：
     • SERVICE_ACCOUNT_PATH: 下载的JSON密钥文件的完整路径。
     • DRIVE_FOLDER_ID: 分享的Google云端硬盘文件夹的ID。 (参见超快速开始中的操作系统特定示例)

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

• 为什么？ 适用于个人用途或本地开发，其中交互式浏览器登录是可以接受的。
• 步骤：
  1. 配置OAuth同意屏幕： 在GCP控制台 -> “API和服务” -> “OAuth同意屏幕”。选择“外部”，填写所需信息，添加范围（.../auth/spreadsheets, .../auth/drive），添加测试用户（如需）。
  2. 创建OAuth客户端ID： 在GCP控制台 -> “API和服务” -> “凭证”。"+ 创建凭证" -> "OAuth客户端ID" -> 类型：桌面应用。命名。"创建"。下载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"; # 使用实际路径
       $bytes = [System.IO.File]::ReadAllBytes($filePath);
       $base64 = [System.Convert]::ToBase64String($bytes);
       $base64 # 复制此输出
       

     • (注意): 避免将敏感凭证粘贴到不受信任的在线编码器中。
  3. 设置环境变量：
     • CREDENTIALS_CONFIG: 将此变量设置为您刚刚生成的完整Base64字符串。

       # 示例（Linux/macOS）- 使用实际生成的字符串
       export CREDENTIALS_CONFIG="ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb..."
       

方法D：应用程序默认凭据（ADC）🌐

• 为什么？ 适用于Google云环境（GKE、Compute Engine、Cloud Run）和本地开发，使用 gcloud auth application-default login。无需显式的凭证文件。
• 如何？ 使用Google的应用程序默认凭据链自动发现来自多个来源的凭证。
• ADC搜索顺序：
  1. GOOGLE_APPLICATION_CREDENTIALS 环境变量（服务账户密钥的路径）- Google的标准变量
  2. gcloud auth application-default login 凭据（本地开发）
  3. 附加的服务账户从元数据服务器（GKE、Compute Engine等）
• 设置：
  • 本地开发：
    1. 运行 gcloud auth application-default login --scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/spreadsheets,https://www.googleapis.com/auth/drive 一次
    2. 设置配额项目：gcloud auth application-default set-quota-project <project_id>（替换 <project_id> 为您的Google云项目ID）
  • Google云： 将服务账户附加到计算资源
  • 环境变量： 设置 GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json（Google的标准）
• 无需额外的环境变量 - 当其他方法失败时，ADC会自动作为回退使用。

注意： GOOGLE_APPLICATION_CREDENTIALS 是Google官方标准环境变量，而 SERVICE_ACCOUNT_PATH 是特定于此MCP服务器的。如果您设置了 GOOGLE_APPLICATION_CREDENTIALS，ADC会自动找到它。

认证优先级及总结

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

1. CREDENTIALS_CONFIG (Base64内容)
2. SERVICE_ACCOUNT_PATH (服务账户JSON的路径)
3. CREDENTIALS_PATH (OAuth JSON的路径) - 如果令牌丢失/过期，会触发交互式流程
4. 应用程序默认凭据（ADC） - 自动回退

环境变量总结：

| 变量 | 方法(s) | 描述 | 默认