mcp-google-sheets

🤔 这是什么？

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

Related MCP server: Spreadsheet MCP Server

🚀 快速入门（使用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 mcp-google-sheets

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中。选择与你的设置匹配的块：

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets"],
      "env": {
        // Use ABSOLUTE paths here
        "SERVICE_ACCOUNT_PATH": "/full/path/to/your/service-account-key.json",
        "DRIVE_FOLDER_ID": "your_shared_folder_id_here"
      },
      "healthcheck_url": "http://localhost:8000/health" // Adjust host/port if needed
    }
  }
}

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets"],
      "env": {
        // Use ABSOLUTE paths here
        "CREDENTIALS_PATH": "/full/path/to/your/credentials.json",
        "TOKEN_PATH": "/full/path/to/your/token.json" // Ensure this path is writable
      },
      "healthcheck_url": "http://localhost:8000/health"
    }
  }
}

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

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets"],
      "env": {
        // Paste the full Base64 string here
        "CREDENTIALS_CONFIG": "ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb3VudCIsCiAgInByb2plY3RfaWQiOiAi...",
        "DRIVE_FOLDER_ID": "your_shared_folder_id_here" // Still needed for Service Account folder context
      },
      "healthcheck_url": "http://localhost:8000/health"
    }
  }
}

{
  "mcpServers": {
    "mcp-google-sheets-dev": { // Use a distinct name
      "command": "uv",
      "args": ["run", "mcp-google-sheets"], // Assumes `mcp-google-sheets` script exists
      "cwd": "/full/path/to/cloned/mcp-google-sheets", // ABSOLUTE path to repo
      "env": {
        // Choose ONE auth method and set corresponding vars
        // Example: Service Account Path
        "SERVICE_ACCOUNT_PATH": "/full/path/to/cloned/mcp-google-sheets/service-account-key.json",
        "DRIVE_FOLDER_ID": "your_shared_folder_id_here"
      },
      "healthcheck_url": "http://localhost:8000/health",
      "disabled": false
    }
  }
}

💬 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 客户端库。