🤔 这是什么？

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

🚀 快速入门（使用 uvx）

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

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

请参阅 ID 参考指南 以获取有关下方使用的 ID 的更多信息。

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 的使用方法 以获取示例。

6. ⚡ 可选：启用工具过滤（减少上下文使用）

   • 默认情况下，所有 19 个工具均被启用（约 13K 个标记）。为了减少上下文使用，您可以仅启用所需的工具。
   • ➡️ 请参阅 工具过滤：减少上下文使用 以获取详细信息。

现在您已经准备就绪！可以通过您的 MCP 客户端开始发出命令了。

✨ 核心特性

• 无缝集成： 直接连接到 Google Drive 和 Google Sheets API。
• 全面的工具集： 提供广泛的操作功能（CRUD、列出、批量处理、共享、格式化等）。
• 灵活的身份验证： 支持服务账号（推荐）、OAuth 2.0，以及通过环境变量直接注入凭据。
• 轻松部署： 使用 uvx 即时运行（无需安装），或使用 uv 克隆以进行开发。
• AI 就绪： 专为与 MCP 兼容的客户端一起使用而设计，支持自然语言的表格交互。
• 工具过滤： 通过 --include-tools 或 ENABLED_TOOLS 环境变量，仅启用您需要的工具，从而减少上下文窗口的使用。

🎯 工具过滤（减少上下文使用）

问题： 默认情况下，此 MCP 服务器会暴露全部 19 个工具，这会在任何对话开始之前消耗约 13,000 个标记。如果您只需要几个工具，这将浪费宝贵的上下文窗口空间。

解决方案： 使用工具过滤功能，仅启用您实际使用的工具。

如何启用工具过滤

您可以通过以下两种方式之一来过滤工具：

1. 命令行参数 --include-tools：

   {
     "mcpServers": {
       "google-sheets": {
         "command": "uvx",
         "args": [
           "mcp-google-sheets@latest",
           "--include-tools",
           "get_sheet_data,update_cells,list_spreadsheets,list_sheets"
         ],
         "env": {
           "SERVICE_ACCOUNT_PATH": "/path/to/credentials.json"
         }
       }
     }
   }
   

2. 环境变量 ENABLED_TOOLS：

   {
     "mcpServers": {
       "google-sheets": {
         "command": "uvx",
         "args": ["mcp-google-sheets@latest"],
         "env": {
           "SERVICE_ACCOUNT_PATH": "/path/to/credentials.json",
           "ENABLED_TOOLS": "get_sheet_data,update_cells,list_spreadsheets,list_sheets"
         }
       }
     }
   }
   

可用工具名称

在筛选时，请使用这些精确的工具名称（以逗号分隔，不含空格）：

最常用工具（推荐子集）：

• get_sheet_data - 从电子表格中读取数据
• update_cells - 向电子表格中写入数据
• list_spreadsheets - 查找电子表格
• list_sheets - 浏览工作表标签

所有可用工具：

• add_columns
• add_rows
• batch_update
• batch_update_cells
• copy_sheet
• create_sheet
• create_spreadsheet
• find_in_spreadsheet
• get_multiple_sheet_data
• get_multiple_spreadsheet_summary
• get_sheet_data
• get_sheet_formulas
• list_folders
• list_sheets
• list_spreadsheets
• rename_sheet
• search_spreadsheets
• share_spreadsheet
• update_cells

注意： 如果既未指定 --include-tools 也未设置 ENABLED_TOOLS，则所有工具都将被启用（默认行为）。

🛠️ 可用工具与资源

本服务器公开了以下用于与 Google 电子表格交互的工具：

有关下方使用的 ID 的更多信息，请参阅 ID 参考指南。

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

• list_spreadsheets: 列出配置的 Drive 文件夹（服务账号）中的电子表格，或当前用户（OAuth）可访问的电子表格。
  • folder_id（可选字符串）：要在其中搜索的 Google Drive 文件夹 ID。从其 URL 中获取。如果省略，则使用配置的默认文件夹，或在“我的云端硬盘”中搜索。
  • 返回值: 对象列表 [{id: string, title: string}]
• create_spreadsheet: 创建一个新的电子表格。
  • title（字符串）：电子表格的期望标题。例如：“第四季度报告”。
  • folder_id（可选字符串）：应在其中创建电子表格的 Google Drive 文件夹 ID。从其 URL 中获取。如果省略，则使用配置的默认文件夹或根目录。
  • 返回值: 包含电子表格信息的对象，包括 spreadsheetId、title 和 folder。
• get_sheet_data: 读取工作表/标签页中某个区域的数据。
  • spreadsheet_id（字符串）：电子表格 ID（从其 URL 中获取）。
  • sheet（字符串）：工作表/标签页的名称（例如：“Sheet1”）。
  • range（可选字符串）：A1 表示法（例如：“A1:C10”、“Sheet1!B2:D”）。如果省略，则读取由 sheet 指定的工作表/标签页的全部内容。
  • include_grid_data（可选布尔值，默认为 False）：如果为 True，则返回包含格式和元数据的完整网格数据（数据量较大）。如果为 False，则仅返回值（效率更高）。
  • 返回值: 如果 include_grid_data=True，则返回包含元数据的完整网格数据（get 响应）。如果为 False，则返回 Values API 的值结果对象（values.get 响应）。
• get_sheet_formulas: 读取工作表/标签页中某个区域的公式。
  • spreadsheet_id（字符串）：电子表格 ID（从其 URL 中获取）。
  • sheet（字符串）：工作表/标签页的名称（例如：“Sheet1”）。
  • range（可选字符串）：A1 表示法（例如：“A1:C10”、“Sheet1!B2:D”）。如果省略，则读取由 sheet 指定的工作表/标签页中的所有公式。
  • 返回值: 单元格公式的二维数组（数组的数组）（values.get 响应）。
• update_cells: 将数据写入特定范围。会覆盖现有数据。
  • spreadsheet_id（字符串）：电子表格 ID（从其 URL 中获取）。
  • sheet（字符串）：工作表/标签页的名称（例如：“Sheet1”）。
  • range（字符串）：要写入的 A1 表示法范围（例如：“A1:C3”）。
  • data（数组的数组）：要写入的二维值数组。例如：[[1, 2, 3], ["a", "b", "c"]]。
  • 返回值: 更新结果对象（values.update 响应）。
• batch_update_cells: 在一次 API 调用中更新多个范围。
  • spreadsheet_id（字符串）：电子表格 ID（从其 URL 中获取）。
  • sheet（字符串）：工作表/标签页的名称（例如：“Sheet1”）。
  • ranges（对象）：将范围字符串（A1 表示法）映射到值的二维数组。例如：{ "A1:B2": [[1, 2], [3, 4]], "D5": [["Hello"]] }。
  • 返回值: 操作结果（values.batchUpdate 响应）。
• add_rows: 在指定索引处向工作表/标签页添加（插入）空行。
  • spreadsheet_id（字符串）：电子表格 ID（从其 URL 中获取）。
  • sheet（字符串）：工作表/标签页的名称（例如：“Sheet1”）。
  • count（整数）：要插入的空行数量。
  • start_row（可选整数，默认为 0）：基于 0 的行索引，用于开始插入行。如果省略，则默认为 0（在开头插入）。
  • 返回值: 操作结果（batchUpdate 响应）。
• list_sheets: 列出电子表格中的所有工作表/标签页名称。
  • spreadsheet_id（字符串）：电子表格 ID（从其 URL 中获取）。
  • 返回值: 工作表/标签页名称字符串列表。例如：["Sheet1", "Sheet2"]。
• create_sheet: 向电子表格添加新的工作表/标签页。
  • spreadsheet_id（字符串）：电子表格 ID（从其 URL 中获取）。
  • title（字符串）：新工作表/标签页的名称。
  • 返回值: 新工作表属性对象。
• get_multiple_sheet_data: 在一次调用中从可能不同的电子表格中的多个范围获取数据。
  • queries（对象数组）：每个对象需要 spreadsheet_id、sheet 和 range。例如：[{"spreadsheet_id": "abc", "sheet": "Sheet1", "range": "A1:B2"}, ...]。
  • 返回值: 对象列表，每个对象包含查询参数和获取到的 data 或 error。每份 data 都是 values.get 响应。
• get_multiple_spreadsheet_summary: 获取多个电子表格的标题、工作表/标签页名称、表头以及前几行数据。
  • spreadsheet_ids（字符串数组）：电子表格的 ID（从其 URLs 中获取）。
  • rows_to_fetch（可选整数，默认为 5）：预览多少行数据（包括表头）。例如：5。
  • 返回值: 每个电子表格的摘要对象列表。
• share_spreadsheet: 将电子表格与指定用户/邮箱及角色共享。
  • spreadsheet_id（字符串）：电子表格 ID（从其 URL 中获取）。
  • recipients（对象数组）：[{"email_address": "user@example.com", "role": "writer"}, ...]。角色包括：reader、commenter、writer。
  • send_notification（可选布尔值，默认为 True）：是否向收件人发送电子邮件通知。
  • 返回值: 包含成功和失败列表的字典。
• add_columns: 在指定索引处向工作表/标签页添加（插入）空列。
  • spreadsheet_id（字符串）：电子表格 ID（从其 URL 中获取）。
  • sheet（字符串）：工作表/标签页的名称（例如：“Sheet1”）。
  • count（整数）：要插入的空列数量。
  • start_column（可选整数，默认为 0）：基于 0 的列索引，用于开始插入。如果省略，则默认为 0（在开头插入）。
  • 返回值: 操作结果（batchUpdate 响应）。
• copy_sheet: 将一个工作表/标签页从一个电子表格复制到另一个，并可选择重命名。
  • src_spreadsheet（字符串）：源电子表格 ID（从其 URL 中获取）。
  • src_sheet（字符串）：源工作表/标签页名称（例如：“Sheet1”）。
  • dst_spreadsheet（字符串）：目标电子表格 ID（从其 URL 中获取）。
  • dst_sheet（字符串）：目标电子表格中希望的新工作表/标签页名称。
  • 返回值: 复制及可选重命名操作的结果。
• rename_sheet: 重命名现有的工作表/标签页。
  • spreadsheet（字符串）：电子表格 ID（从其 URL 中获取）。
  • sheet（字符串）：当前工作表/标签页名称（例如：“Sheet1”）。
  • new_name（字符串）：新的工作表/标签页名称（例如：“Transactions”）。
  • 返回值: 操作结果（batchUpdate 响应）。
• add_chart: 根据指定数据在 Google 表格中创建图表。
  • spreadsheet_id（字符串）：电子表格 ID（从其 URL 中获取）。
  • sheet（字符串）：包含数据的工作表/标签页名称（例如：“Sheet1”）。
  • chart_type（字符串）：要创建的图表类型。选项包括：COLUMN（垂直柱状图）、BAR（水平柱状图）、LINE、AREA、PIE、SCATTER、COMBO、HISTOGRAM。
  • data_range（字符串）：用于图表数据的 A1 表示法范围（例如：“A1:C10”）。第一行被视为表头。
  • title（可选字符串）：图表标题。
  • x_axis_label（可选字符串）：X 轴（底部轴）的标签。不适用于饼图。
  • y_axis_label（可选字符串）：Y 轴（左侧轴）的标签。不适用于饼图。
  • position_x（可选整数，默认为 0）：从左上角开始的水平偏移像素数。
  • position_y（可选整数，默认为 0）：从左上角开始的垂直偏移像素数。
  • width（可选整数，默认为 600）：图表的宽度（以像素为单位）。
  • height（可选整数，默认为 400）：图表的高度（以像素为单位）。
  • 返回值: 包含成功状态、图表 ID 和操作详情的结果对象。

MCP 资源：

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

☁️ Google Cloud Platform 设置（详细）

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

1. 创建或选择 GCP 项目: 前往 Google Cloud 控制台。
2. 启用 API: 导航到“API 和服务”->“库”。搜索并启用：
   • Google Sheets API
   • Google Drive API
3. 配置凭据: 您需要从以下方法中选择一种身份验证方式（推荐使用服务账户）。

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

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

有关下方使用的 ID 的更多信息，请参阅ID 参考指南。

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

• 为什么？ 无头模式（无需浏览器），安全，非常适合服务器环境。不易过期。
• 步骤：
  1. 创建服务账户: 在 GCP 控制台 -> “IAM 和管理员” -> “服务账户”。
     • 点击“+ 创建服务账户”。为其命名（例如 mcp-sheets-service）。
     • 授予角色：添加 编辑者 角色以获得广泛权限，或更细粒度的角色（如 roles/drive.file 和特定的 Sheets 角色）以获得更严格的权限。
     • 点击“完成”。找到该账户，点击操作按钮 (⋮) -> “管理密钥”。
     • 点击“添加密钥” -> “创建新密钥” -> JSON -> “创建”。
     • 下载并安全存储 JSON 密钥文件。
  2. 创建并共享 Google 云端硬盘文件夹:
     • 在 Google 云端硬盘 中，创建一个文件夹（例如“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 云端硬盘文件夹的 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 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 等）
• 设置：
  • 本地开发：
    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 Cloud 项目 ID）
  • 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)——自动回退

环境变量摘要：

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

有关下方使用的 ID 的更多信息，请参阅 ID 参考指南。

方法 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
   

方法 3：Docker（SSE 传输）

使用附带的 Dockerfile 在容器中运行服务器：

# 构建镜像
docker build -t mcp-google-sheets .

# 运行（SSE 使用 8000 端口）
# 注意：在容器中建议使用 CREDENTIALS_CONFIG（Base64 编码的凭据内容）。
docker run --rm -p 8000:8000 ^
  -e HOST=0.0.0.0 ^
  -e PORT=8000 ^
  -e CREDENTIALS_CONFIG=YOUR_BASE64_CREDENTIALS ^
  -e DRIVE_FOLDER_ID=YOUR_DRIVE_FOLDER_ID ^
  mcp-google-sheets

• 在 Docker 容器内应使用 CREDENTIALS_CONFIG 而不是 SERVICE_ACCOUNT_PATH，以避免将敏感信息作为文件挂载。
• 容器启动时会使用 --transport sse 并监听 HOST/PORT。请将您的 MCP 客户端指向 http://localhost:8000，并使用 SSE 传输方式。

🔌 与 Claude Desktop 的使用

将服务器配置添加到 claude_desktop_config.json 文件中的 mcpServers 部分。根据你的设置选择相应的配置块：

请参阅 ID 参考指南 以获取有关以下 ID 的更多信息。

⚠️ 重要提示：

• 🍎 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 电子表格文件夹中”）
• “创建一个名为‘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。不要发送通知。”
• “在我的‘销售报告’电子表格中，根据 A1:B13 范围的数据，创建一个显示每月收入的柱状图。”
• “在‘市场分析’工作表中添加一个饼图，数据来自 A1:B5，标题为‘按产品划分的市场份额’。”
• “在电子表格 abc123 中，于 Sheet1 上基于 A1:C10 范围创建一个折线图，标题为‘增长趋势’，并标注‘月份’和‘收入’。”

🆔 ID 参考指南

请使用以下参考指南查找文档中提到的各种 ID：

Google Cloud 项目 ID：
  https://console.cloud.google.com/apis/dashboard?project=sheets-mcp-server-123456
                                                          └───── 项目 ID ─────┘

Google Drive 文件夹 ID：
  https://drive.google.com/drive/u/0/folders/1xcRQCU9xrNVBPTeNzHqx4hrG7yR91WIa
                                             └────────── 文件夹 ID ──────────┘

Google Sheets 电子表格 ID：
  https://docs.google.com/spreadsheets/d/25_-_raTaKjaVxu9nJzA7-FCrNhnkd3cXC54BPAOXemI/edit
                                         └───────────── 电子表格 ID ─────────────┘

🤝 贡献

欢迎贡献！请提交问题以讨论错误或功能请求。也欢迎提交拉取请求。

📄 许可证

本项目采用 MIT 许可证授权 - 详情请参阅 LICENSE 文件。

🙏 致谢

• 基于 FastMCP 构建。
• 灵感来源于 kazz187/mcp-google-spreadsheet。
• 使用 Google API Python 客户端库。

mcp-google-sheets 快速上手指南

mcp-google-sheets 是一个基于 Python 的 MCP 服务器，作为 AI 助手（如 Claude Desktop）与 Google Sheets API 之间的桥梁。它允许你通过自然语言指令操作 Google 表格，实现强大的自动化和数据管理工作流。

环境准备

在开始之前，请确保满足以下要求：

1. 操作系统：支持 macOS、Linux 或 Windows。
2. Google Cloud 账号：你需要拥有一个 Google Cloud Platform (GCP) 项目。
3. 前置依赖：
   • 启用 API：在 GCP 控制台中启用 Google Sheets API 和 Google Drive API。
   • 服务账号 (Service Account)：创建一个服务账号，下载其 JSON 密钥文件（推荐方式），并将该服务账号添加到你需要访问的 Google Drive 文件夹中（赋予“编辑者”权限）。
   • 获取 ID：准备好目标 Drive 文件夹的 ID（从文件夹 URL 中获取）。

安装步骤

本项目推荐使用 uv (一个极速的 Python 包管理器) 运行，无需手动创建虚拟环境或安装依赖。

1. 安装 uv

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

安装完成后，请根据终端提示将 uv 添加到系统 PATH 环境变量中。

2. 配置环境变量

设置认证所需的凭证路径和 Drive 文件夹 ID。

macOS / Linux (Bash/Zsh):

export SERVICE_ACCOUNT_PATH="/绝对路径/到你的/service-account-key.json"
export DRIVE_FOLDER_ID="你的_DRIVE_文件夹_ID"

Windows (CMD):

set SERVICE_ACCOUNT_PATH="C:\绝对路径\到你的\service-account-key.json"
set DRIVE_FOLDER_ID="你的_DRIVE_文件夹_ID"

Windows (PowerShell):

$env:SERVICE_ACCOUNT_PATH = "C:\绝对路径\到你的\service-account-key.json"
$env:DRIVE_FOLDER_ID = "你的_DRIVE_文件夹_ID"

注意：请将路径替换为你实际的 JSON 密钥文件路径，将 ID 替换为你的 Google Drive 文件夹 ID。

基本使用

1. 启动服务器

使用 uvx 直接运行最新版本的服务器。该命令会自动下载并执行代码。

uvx mcp-google-sheets@latest

建议始终添加 @latest 以确保获取最新功能和修复。

启动成功后，终端将显示日志表明服务器已就绪。

2. 连接 MCP 客户端

配置你的 MCP 客户端（例如 Claude Desktop）以连接此服务器。以下是一个典型的 claude_desktop_config.json 配置示例：

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {
        "SERVICE_ACCOUNT_PATH": "/绝对路径/到你的/service-account-key.json",
        "DRIVE_FOLDER_ID": "你的_DRIVE_文件夹_ID"
      }
    }
  }
}

重启客户端后，即可在对话中使用自然语言操作表格，例如：

• “列出我驱动文件夹里的所有表格”
• “在 'Sales' 表格的 'Sheet1' 中 A1 到 C3 区域写入数据 [[1, 2, 3], [4, 5, 6]]"
• “读取 'Report' 表格中的所有数据”

3. 优化：按需加载工具 (可选)

默认情况下服务器会加载所有 19 个工具（消耗约 13k tokens）。若只需常用功能，可通过 --include-tools 参数或 ENABLED_TOOLS 环境变量仅启用特定工具，以节省上下文窗口。

示例：仅启用读取、写入和列表功能

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": [
        "mcp-google-sheets@latest",
        "--include-tools",
        "get_sheet_data,update_cells,list_spreadsheets,list_sheets"
      ],
      "env": {
        "SERVICE_ACCOUNT_PATH": "/绝对路径/到你的/service-account-key.json",
        "DRIVE_FOLDER_ID": "你的_DRIVE_文件夹_ID"
      }
    }
  }
}

可用工具名包括：get_sheet_data, update_cells, list_spreadsheets, list_sheets, create_spreadsheet, batch_update_cells 等。