M

MCP Google表格服务器

@xing5/mcp-google-sheets
1 Stars 477 次浏览 xing5 更新于 2026-08-23

一种集成了Google Drive和Google Sheets的模型上下文协议服务器，允许用户通过自然语言命令创建、读取、更新和管理电子表格。

开发者工具文件系统

MCP 服务配置

复制以下 JSON 到 OPClaw 或其他 MCP 客户端的配置文件中即可使用

{
  "mcpServers": {
    "google-sheets": {
      "args": [
        "mcp-google-sheets@latest"
      ],
      "command": "uvx",
      "env": {}
    }
  }
}

该服务需要配置环境变量：CREDENTIALS_PATH、DRIVE_FOLDER_ID、SERVICE_ACCOUNT_PATH、TOKEN_PATH

服务介绍

PyPI - Version
PyPI - Downloads
GitHub License
GitHub Actions Workflow Status

🤔 这是什么？

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

🚀 快速开始（使用 uvx）

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

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

  1. ☁️ 前提条件：Google Cloud 设置

  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.
    • Returns: Dictionary with successes and failures lists.
  • add_columns: Adds columns to a sheet. (Verify parameters if implemented)
  • copy_sheet: Duplicates a sheet within a spreadsheet. (Verify parameters if implemented)
  • rename_sheet: Renames an existing sheet. (Verify parameters if implemented)

MCP 资源：

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

☁️ Google Cloud Platform 设置（详细）

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

  1. 创建/选择 GCP 项目： 前往 Google Cloud 控制台。
  2. 启用 API： 导航到“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 控制台 -> "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..."

认证优先级与总结

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

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

环境变量摘要：

变量 方法(s) 描述 默认值
SERVICE_ACCOUNT_PATH 服务账号 服务账号 JSON 密钥文件的路径。 -
DRIVE_FOLDER_ID 服务账号 与服务账号共享的 Google Drive 文件夹 ID。 -
CREDENTIALS_PATH OAuth 2.0 OAuth 2.0 客户端 ID JSON 文件的路径。 credentials.json
TOKEN_PATH OAuth 2.0 存储生成的 OAuth 令牌的路径。 token.json
CREDENTIALS_CONFIG 服务账号 / OAuth 2.0 凭证内容的 Base64 编码 JSON 字符串。 -

⚙️ 运行服务器（详细说明）

方法 1：使用 uvx（推荐给用户）

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

uvx mcp-google-sheets

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

方法 2：开发用途（克隆仓库）

如果您想修改代码：

  1. 克隆: git clone https://github.com/yourusername/mcp-google-sheets.git && cd mcp-google-sheets（请使用实际 URL）
  2. 设置环境变量： 如上所述。
  3. 使用 uv 运行：（使用本地代码） 
    uv run mcp-google-sheets
# 或者如果在 pyproject.toml 中定义了脚本名称，则：
# uv run start

🔌 与 Claude 桌面版配合使用

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

{
  "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’的新工作表。”
  • “在我的‘项目任务’电子表格中，将‘Tasks’工作表中的B2单元格更新为‘进行中’。”
  • “将这些行追加到电子表格XYZ的‘Log’工作表中：[['2024-07-31', 'Task A Completed'], ['2024-08-01', 'Task B Started']]”
  • “获取‘销售数据’和‘库存计数’电子表格的摘要。”
  • “与team@example.com共享‘团队假期安排’电子表格，权限设置为只读；与manager@example.com共享，权限设置为可写。不发送通知。”

🤝 贡献

欢迎贡献！请打开一个问题来讨论错误或功能请求。我们非常欢迎拉取请求。

📄 许可证

本项目根据MIT许可证发布 - 详情请参阅LICENSE文件。

🙏 致谢

查看源码 项目主页

相关 MCP 服务

LeetCode(力扣)
jinzcdev/leetcode-mcp-server
MCP 服务器实现 LeetCode API 集成，支持自动化获取编程题库、用户数据和竞赛信息。
可视化图表-MCP-Server
antvis/mcp-server-chart
这是一个基于AntV的模型上下文协议服务器，用于生成图表。它支持超过20种类型的图表，并且可以与多种桌面应用程序和平台一起使用。
微软Playwright
@microsoft/playwright-mcp
一种模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页交互，而无需使用视觉模型或截图。
MCP上下文模型文档
@upstash/context7-mcp
一种模型上下文协议服务器，它从库中直接获取最新、特定版本的文档和代码示例并将其引入LLM提示中，帮助开发人员在无需过时或虚构信息的情况下获得准确的答案。