xing5/mcp-google-sheets

🤔 这是什么？

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

🚀 快速入门（使用 uvx）

本质上服务器在一行中运行：uvx mcp-google-sheets@latest。

这条命令将自动下载最新代码并运行它。我们强烈建议始终使用 @latest 以确保您拥有最新版本，包含最新的功能和错误修复。

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

   • 您必须首先配置Google Cloud Platform凭证并启用必要的API。我们强烈建议使用服务账户。
   • ➡️ 跳转到下方的详细Google Cloud Platform设置指南。

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@latest
     

   • 服务器将启动并打印日志指示其已准备好。

   • 💡 小贴士： 始终使用 @latest 以确保您获得最新版本，包含错误修复和功能。如果没有 @latest，uvx 可能会使用缓存的旧版本。

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：列出配置的Drive文件夹中的电子表格（服务账户）或用户可访问的电子表格（OAuth）。
  • 返回： 电子表格对象列表 [[{id: string, title: string}]]
• create_spreadsheet：创建一个新的电子表格。
  • title (string): 希望的标题。
  • 返回： 包含电子表格信息的对象，包括 spreadsheetId。
• get_sheet_data：从电子表格中的某个范围读取数据。
  • spreadsheet_id (string)
  • sheet (string): 电子表格的名称。
  • range (可选 string): A1表示法（例如，'A1:C10'，'Sheet1!B2:D'）。如果省略，则读取整个电子表格。
  • 返回： 来自Google Sheets API的完整网格数据结构，并保留所有元数据。
• get_sheet_formulas：从电子表格中的某个范围读取公式。
  • spreadsheet_id (string)
  • sheet (string): 电子表格的名称。
  • range (可选 string): A1表示法（例如，'A1:C10'，'Sheet1!B2:D'）。如果省略，则读取整个电子表格。
  • 返回： 2D数组形式的单元格公式。
• update_cells：将数据写入特定范围。覆盖现有数据。
  • spreadsheet_id (string)
  • sheet (string)
  • range (string): A1表示法。
  • data (2D array): 要写入的值。
  • 返回： 更新结果对象。
• batch_update_cells：在一个API调用中更新多个范围。
  • spreadsheet_id (string)
  • sheet (string)
  • ranges (object)：范围字符串（A1表示法）到2D数组值映射的字典 { "A1:B2": [[1, 2], [3, 4]], "D5": [["Hello"]] }。
  • 返回： 批量更新结果对象。
• add_rows：将行追加到电子表格的末尾（在最后一个有数据的行之后）。
  • spreadsheet_id (string)
  • sheet (string)
  • data (2D array)：要追加的行。
  • 返回： 更新结果对象。
• list_sheets：列出电子表格中的所有工作表名称。
  • spreadsheet_id (string)
  • 返回： 工作表名称字符串列表 ["Sheet1", "Sheet2"]。
• create_sheet：向电子表格添加一个新的工作表（选项卡）。
  • spreadsheet_id (string)
  • title (string)：新工作表的名称。
  • 返回： 新工作表属性对象。
• get_multiple_sheet_data：在一个调用中获取跨潜在不同电子表格的多个范围的数据。
  • queries (array of objects)：每个对象都需要 spreadsheet_id，sheet 和 range。 [{spreadsheet_id: 'abc', sheet: 'Sheet1', range: 'A1:B2'}, ...]。
  • 返回： 对象列表，每个对象包含查询参数和获取的 data 或 error。
• get_multiple_spreadsheet_summary：获取多个电子表格的标题、工作表名称、标题和前几行。
  • spreadsheet_ids (array of strings)
  • rows_to_fetch (可选 integer, default 5)：要预览的行数（包括标题）。
  • 返回： 每个电子表格的摘要对象列表。
• share_spreadsheet：与指定的用户/电子邮件和角色共享电子表格。
  • spreadsheet_id (string)
  • recipients (array of objects)：[{email_address: 'user@example.com', role: 'writer'}, ...]。角色：reader，commenter，writer。
  • send_notification (可选 boolean, default True)：发送电子邮件通知。
  • 返回： 包含 successes 和 failures 列表的字典。
• add_columns：向工作表添加列。(如果实现，请验证参数)
• copy_sheet：在电子表格内复制工作表。(如果实现，请验证参数)
• rename_sheet：重命名现有工作表。(如果实现，请验证参数)

MCP资源：

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

☁️ Google Cloud Platform设置（详细）

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

1. 创建/选择GCP项目： 前往Google Cloud Console。
2. 启用API： 导航到 "APIs & Services" -> "Library"。搜索并启用：
   • Google Sheets API
   • Google Drive API
3. 配置凭证： 您需要选择以下一种身份验证方法（服务账户推荐）。

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

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

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

• 为什么？ 无头（无需浏览器），安全，理想的服务器环境。不易过期。
• 步骤：
  1. 创建服务账户： 在GCP Console -> "IAM & Admin" -> "Service Accounts"。
     • 点击 "+ CREATE SERVICE ACCOUNT"。命名它（例如，mcp-sheets-service）。
     • 授予角色：添加 Editor 角色（广泛访问），或更细粒度的角色（如 roles/drive.file 和特定的Sheets角色）以进行更严格的权限控制。
     • 点击 "Done"。找到该账户，点击操作（⋮）-> "Manage keys"。
     • 点击 "ADD KEY" -> "Create new key" -> JSON -> "CREATE"。
     • 下载并安全存储 JSON密钥文件。
  2. 创建并共享Google Drive文件夹：
     • 在 Google Drive 中创建一个文件夹（例如，"AI Managed Sheets"）。
     • 从URL中注意文件夹ID：https://drive.google.com/drive/folders/THIS_IS_THE_FOLDER_ID。
     • 右键单击文件夹 -> "Share" -> "Share"。
     • 输入服务账户的电子邮件地址（来自JSON文件 client_email）。
     • 授予 Editor 访问权限。取消选中 "Notify people"。点击 "Share"。
  3. 设置环境变量：
     • SERVICE_ACCOUNT_PATH：下载的JSON密钥文件的完整路径。
     • DRIVE_FOLDER_ID：共享的Google Drive文件夹的ID。 (参见快速入门以获取特定于操作系统的示例)

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

• 为什么？ 对于个人使用或本地开发，交互式浏览器登录是可行的。
• 步骤：
  1. 配置OAuth同意屏幕： 在GCP Console -> "APIs & Services" -> "OAuth consent screen"。选择 "External"，填写必要信息，添加范围（.../auth/spreadsheets，.../auth/drive），如果需要，添加测试用户。
  2. 创建OAuth客户端ID： 在GCP Console -> "APIs & Services" -> "Credentials"。"+ CREATE CREDENTIALS" -> "OAuth client 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"; # 使用实际路径
       $bytes = [System.IO.File]::ReadAllBytes($filePath);
       $base64 = [System.Convert]::ToBase64String($bytes);
       $base64 # 复制此输出
       

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

       # 示例 (Linux/macOS) - 使用实际生成的字符串
       export CREDENTIALS_CONFIG="ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb3VudCIsCiAgInByb2plY3RfaWQiOiAi..."
       

方法D：应用默认凭证（ADC） 🌐

• 为什么？ 理想用于Google Cloud环境（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等）
• 设置：
  • 本地开发： 运行 gcloud auth application-default login 一次
  • Google Cloud： 将服务账户附加到您的计算资源
  • 环境变量： 设置 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） - 自动回退

环境变量摘要：

⚙️ 运行服务器（详细）

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

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

uvx mcp-google-sheets@latest

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 Desktop一起使用

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

⚠️ 重要说明：

• 🍎 macOS用户： 使用完整路径："/Users/yourusername/.local/bin/uvx" 而不是 "uvx"

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {
        "SERVICE_ACCOUNT_PATH": "/full/path/to/your/service-account-key.json",
        "DRIVE_FOLDER_ID": "your_shared_folder_id_here"
      }
    }
  }
}

{
  "mcpServers": {
    "google-sheets": {
      "command": "/Users/yourusername/.local/bin/uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {
        "SERVICE_ACCOUNT_PATH": "/full/path/to/your/service-account-key.json",
        "DRIVE_FOLDER_ID": "your_shared_folder_id_here"
      }
    }
  }
}

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {
        "CREDENTIALS_PATH": "/full/path/to/your/credentials.json",
        "TOKEN_PATH": "/full/path/to/your/token.json"
      }
    }
  }
}

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {
        "CREDENTIALS_CONFIG": "ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb3VudCIsCiAgInByb2plY3RfaWQiOiAi...",
        "DRIVE_FOLDER_ID": "your_shared_folder_id_here"
      }
    }
  }
}

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json"
      }
    }
  }
}

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

{
  "mcpServers": {
    "mcp-google-sheets-local": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/your/mcp-google-sheets",
        "mcp-google-sheets"
      ],
      "env": {
        "SERVICE_ACCOUNT_PATH": "/path/to/your/mcp-google-sheets/service_account.json",
        "DRIVE_FOLDER_ID": "your_drive_folder_id_here"
      }
    }
  }
}

💬 Claude的示例提示

连接后，尝试提示如下：

• "列出我所有可以访问的电子表格。"（或 "在我的AI Managed Sheets文件夹中"）
• "创建一个名为 'Quarterly Sales Report Q3 2024' 的新电子表格。"
• "在我的 'Quarterly Sales Report' 电子表格中，获取Sheet1范围A1到E10的数据。"
• "在我的 'Project Tasks' 电子表格，Sheet 'Tasks' 中，将单元格B2更改为 'In Progress'。"
• "将以下行追加到 'Log' 工作表：电子表格 XYZ。 [['2024-07-31', 'Task A Completed'], ['2024-08-01', 'Task B Started']]"
• "获取 'Sales Data' 和 'Inventory Count' 电子表格的摘要。"
• "与 'Team Vacation Schedule' 电子表格共享 team@example.com 作为阅读者，manager@example.com 作为写入者。不要发送通知。"

🤝 贡献

欢迎贡献！请打开问题以讨论错误或功能请求。拉取请求是受欢迎的。

📄 许可证

本项目根据MIT许可证授权 - 详细内容请参阅许可证文件。

🙏 致谢

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