关键词

Google SheetsAI表格数据自动化云存储生产力工具

项目简介

'mcp-google-sheets' 是一个基于 Model Context Protocol (MCP) 构建的 Python 服务器，旨在作为AI助手（如 Claude Desktop）与 Google Sheets API 之间的桥梁。它使得通过自然语言或结构化指令，由AI直接访问、操作和管理您的Google表格文件成为可能。

主要功能点

  • 表格文件管理: 列出特定文件夹或“我的云端硬盘”中的Google表格文件。
  • 表格创建与管理: 创建新的Google表格文件，在现有表格中添加或复制工作表，以及重命名工作表。
  • 数据读写: 读取工作表中指定范围的数据，或向指定范围写入数据。
  • 批量操作: 支持一次性向多个单元格或范围进行批量数据更新。
  • 追加行: 在工作表的末尾添加新的数据行。
  • 列管理: 在工作表中添加新的列。
  • 信息查询: 获取特定Google表格的基本信息（标题、工作表列表等）。
  • 多表格摘要: 快速获取多个Google表格的概览信息，包括工作表名称和前几行数据（通常用于预览）。
  • 表格分享: 将Google表格分享给指定的用户邮箱，并设置其权限（读者、评论者、编辑者）。
  • 灵活的身份验证: 支持 Google 服务账号（推荐用于自动化）、OAuth 2.0（适合个人交互使用）以及直接通过环境变量注入凭据内容。

安装步骤

该项目推荐使用 'uvx' 工具进行安装和运行，实现“零安装”体验。

  1. Google Cloud 设置: 这是必要的前提步骤。
    • 访问 Google Cloud 控制台，创建或选择一个项目。
    • 在“API和服务” -> “API库”中启用 'Google Sheets API' 和 'Google Drive API'。
    • 在“API和服务” -> “凭据”中，根据您的需求（服务账号或 OAuth 客户端ID）创建并下载凭据文件（JSON格式）。服务账号推荐，因为它无需交互式登录且适合服务器环境。
    • 如果您使用服务账号，请在 Google Drive 中创建一个用于存放AI管理表格的文件夹，并将其分享给您的服务账号邮箱（赋予编辑权限），记下该文件夹的ID。
  2. 安装 'uv': 'uvx' 是 'uv' 的一部分。请根据您的操作系统，使用以下命令之一安装 'uv'：
    • 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' 和 'uvx' 命令已添加到您的系统PATH中。
  3. 设置环境变量: 在运行服务器之前，根据您选择的身份验证方式，在终端中设置必要的环境变量。例如：
    • 服务账号: 设置 'SERVICE_ACCOUNT_PATH' 为您的服务账号 JSON 文件的完整路径，以及 'DRIVE_FOLDER_ID' 为您共享给服务账号的 Google Drive 文件夹ID。
    • OAuth 2.0: 设置 'CREDENTIALS_PATH' 为您的 OAuth 客户端 ID JSON 文件的路径，以及 'TOKEN_PATH' 为用于存储用户身份验证令牌文件的可写路径（如 'token.json'）。
    • 直接注入: 设置 'CREDENTIALS_CONFIG' 为您凭据 JSON 文件内容的 Base64 编码字符串。
  4. 运行服务器: 在设置好环境变量的终端中，运行以下命令启动服务器： 
    uvx mcp-google-sheets
    'uvx' 会自动下载并运行最新版本的 'mcp-google-sheets' 服务器。

服务器配置 (供 MCP 客户端参考)

要让支持 MCP 的客户端（如某些AI桌面应用）连接到 'mcp-google-sheets' 服务器，您需要在客户端的配置中添加该服务器的信息。这通常是一个 JSON 格式的配置片段。客户端需要知道如何启动或连接到服务器，关键信息包括：

  • 服务器名称 (server name): 一个标识符，如 '"google-sheets"'。
  • 启动命令 (command): 启动服务器的可执行文件或脚本路径，例如 '"uvx"'。
  • 启动参数 (args): 传递给启动命令的参数，例如 '["mcp-google-sheets"]'。
  • 环境变量 (env): 服务器运行时需要的环境变量，特别是用于 Google 身份验证的变量（'SERVICE_ACCOUNT_PATH' 和 'DRIVE_FOLDER_ID'，或 'CREDENTIALS_PATH' 和 'TOKEN_PATH'，或 'CREDENTIALS_CONFIG'）。请确保路径是绝对路径。
  • 健康检查URL (healthcheck_url): 可选，用于客户端检查服务器是否正常运行的URL，通常是 '"http://localhost:8000/health"'（如果服务器运行在默认端口）。

具体的配置格式和位置取决于您使用的MCP客户端。请查阅您的AI助手客户端文档以了解如何添加外部MCP服务器。

基本使用方法

服务器运行并客户端连接成功后，您就可以通过AI助手的交互界面（通常是聊天界面）来使用Google Sheets功能了。AI助手会根据您的自然语言指令，自动调用 'mcp-google-sheets' 服务器提供的工具。

例如，您可以尝试向AI助手发送以下指令（AI助手会将其转化为对服务器工具的调用）：

  • “帮我列出我的Google表格文件。” (调用 'list_spreadsheets' 工具)
  • “创建一个名为‘项目预算表’的新Google表格。” (调用 'create_spreadsheet' 工具)
  • “在ID为 '1aBcDeFgHiJkLmNoPqRsTuVwXyZ' 的表格中，获取 Sheet1 工作表 A1 到 C10 范围的数据。” (调用 'get_sheet_data' 工具)
  • “在‘销售数据’表格的‘汇总’工作表中，将单元格 B5 的值更新为 ‘完成’。” (调用 'update_cells' 工具)
  • “将这张表格分享给 [email protected]，权限设置为编辑者。” (调用 'share_spreadsheet' 工具)

通过这些工具，您可以让AI助手辅助完成表格数据的查询、录入、整理和管理任务。

故障排除

  • 确保已完成所有 Google Cloud 设置步骤，并启用了正确的API。
  • 检查环境变量是否已正确设置，特别是凭据文件路径和文件夹ID是否准确且服务器进程可访问。
  • 如果是 OAuth 方式，首次运行时可能需要在浏览器中完成 Google 授权。
  • 检查服务器日志输出，通常能找到认证失败、权限不足或API调用错误等信息。

信息

分类

生产力应用

访问项目