mcp-google-sheets：Google Sheets MCP 服务器

此 MCP 服务器与您的 Google Drive 和 Google Sheets 集成，以便创建和修改电子表格。

概述

用于与 Google 表格交互的模型上下文协议服务器。该服务器提供通过 Google 表格 API 创建、读取、更新和管理电子表格的工具。

工具

get_sheet_data
- 从 Google 电子表格中的特定工作表获取数据
- 输入：
  - spreadsheet_id (字符串)：电子表格的 ID（可在 URL 中找到）
  - sheet （字符串）：工作表的名称
  - range （可选字符串）：A1 格式的单元格范围（例如，'A1:C10'）
- 返回：工作表数据的二维数组
update_cells
- 更新 Google 电子表格中的单元格
- 输入：
  - spreadsheet_id （字符串）：电子表格的 ID
  - sheet （字符串）：工作表的名称
  - range （字符串）：A1 符号中的单元格范围
  - data （二维数组）：要更新的值
- 返回：更新操作的结果
batch_update_cells
- 批量更新Google电子表格中的多个范围
- 输入：
  - spreadsheet_id （字符串）：电子表格的 ID
  - sheet （字符串）：工作表的名称
  - ranges （对象）：将范围字符串映射到二维数组值的字典
- 返回：批量更新操作的结果
list_sheets
- 列出 Google 电子表格中的所有工作表
- 输入：
  - spreadsheet_id （字符串）：电子表格的 ID
- 返回：工作表名称列表
list_spreadsheets
- 列出配置的 Google Drive 文件夹中的所有电子表格
- 返回：电子表格列表及其 ID 和标题
- 注意：如果使用服务帐户身份验证，这将列出共享文件夹中的电子表格
create_spreadsheet
- 创建新的 Google 电子表格
- 输入：
  - title （字符串）：新电子表格的标题
- 返回：有关新创建的电子表格的信息，包括其 ID
- 注意：当使用已配置文件夹 ID 的服务帐户身份验证时，电子表格将在该文件夹中创建
create_sheet
- 在现有的 Google 电子表格中创建新的工作表标签
- 输入：
  - spreadsheet_id （字符串）：电子表格的 ID
  - title （字符串）：新表的标题
- 返回：有关新创建的工作表的信息
附加工具： add_rows 、 add_columns 、 copy_sheet 、 rename_sheet

资源

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

安装和设置

服务器需要在 Google Cloud Platform 中进行一些设置，并在运行之前选择一种身份验证方法。

Google Cloud Platform 设置（所有方法均需）

创建 Google Cloud Platform 项目：
- 前往Google Cloud Console
- 创建新项目或选择现有项目
- 启用 Google Sheets API 和 Google Drive API

选择身份验证方法

您可以使用以下两种身份验证方法之一：

方法一：服务账户认证（推荐，非交互）

服务帐号提供无头身份验证，无需浏览器提示，非常适合自动化或服务器环境。其优势包括：

无需浏览器交互即可进行身份验证
在无头环境中运行良好
身份验证不像 OAuth 令牌那样频繁过期
非常适合服务器部署和自动化

设置步骤：

创建服务帐户：
- 前往 Google Cloud Console → IAM 和管理 → 服务帐户
- 创建一个具有描述性名称的新服务帐户
- 授予其适当的角色（用于访问 Google Sheets）
- 创建并下载 JSON 密钥文件
在 Google Drive 中创建一个专用文件夹与服务帐户共享：
- 前往 Google Drive 并创建一个新文件夹（例如“Claude Sheets”）
- 从 URL 中记下文件夹的 ID： https://drive.google.com/drive/folders/FOLDER_ID_HERE
- 右键单击文件夹并选择“共享”
- 与服务帐户电子邮件地址共享（在 JSON 文件中找到为client_email ）
- 授予其“编辑”权限
设置以下环境变量：
- SERVICE_ACCOUNT_PATH ：服务帐户 JSON 密钥文件的路径
- DRIVE_FOLDER_ID ：与服务帐户共享的 Google Drive 文件夹的 ID

方法 2：OAuth 2.0 身份验证（交互式）

此方法首次设置时需要浏览器交互，适合个人使用或开发。

为您的项目配置 OAuth：
- 配置 OAuth 同意屏幕
- 创建 OAuth 2.0 客户端 ID 凭据（桌面应用程序类型）
- 下载凭证 JSON 文件并将其保存为credentials.json
设置以下环境变量：
- CREDENTIALS_PATH ：下载的 OAuth 凭证文件的路径（默认值： credentials.json ）
- TOKEN_PATH ：存储身份验证令牌的路径（默认值： token.json ）

设置环境变量

对于Linux / Mac：

# For service account authentication (recommended)
export SERVICE_ACCOUNT_PATH=/path/to/your/service-account-key.json
export DRIVE_FOLDER_ID=your_shared_folder_id_here

# OR for OAuth authentication
export CREDENTIALS_PATH=/path/to/your/credentials.json
export TOKEN_PATH=/path/to/your/token.json

对于 Windows：

# For service account authentication (recommended)
set SERVICE_ACCOUNT_PATH=C:\path\to\your\service-account-key.json
set DRIVE_FOLDER_ID=your_shared_folder_id_here

# OR for OAuth authentication
set CREDENTIALS_PATH=C:\path\to\your\credentials.json
set TOKEN_PATH=C:\path\to\your\token.json

运行服务器

方法一：使用uvx（建议正常使用）

使用uvx时，无需安装即可直接运行服务器：

# Set environment variables first, then run the server
uvx mcp-google-sheets

方法2：用于开发和修改

如果要修改开发服务器：

克隆存储库：

git clone https://github.com/yourusername/mcp-google-sheets.git
cd mcp-google-sheets

使用 uv 运行：

# Set environment variables first, then run
uv run mcp-google-sheets

身份验证过程

服务器根据环境变量自动选择身份验证方法：

首先，它检查服务帐户凭据（非交互式）
如果服务帐户身份验证失败或未配置，则回退到 OAuth 流程

通过服务帐户身份验证，无需浏览器交互，服务器将直接对共享的 Google Drive 文件夹中的电子表格进行操作。

使用 OAuth 身份验证时，首次使用服务器时，它会打开一个浏览器窗口，以便使用您的 Google 帐户进行身份验证。身份验证完成后，令牌将保存在TOKEN_PATH环境变量指定的位置。

与 Claude Desktop 一起使用

将其添加到您的claude_desktop_config.json中：

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

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

"mcpServers": {
  "mcp-google-sheets": {
    "command": "uv",
    "args": [
      "--directory",
      "/path/to/mcp-google-sheets",
      "run",
      "mcp-google-sheets"
    ],
    "env": {
      "SERVICE_ACCOUNT_PATH": "/path/to/mcp-google-sheets/service-account-key.json",
      "DRIVE_FOLDER_ID": "your_shared_folder_id_here"
      // OR for OAuth: 
      // "CREDENTIALS_PATH": "/path/to/mcp-google-sheets/credentials.json",
      // "TOKEN_PATH": "/path/to/mcp-google-sheets/token.json"
    },
    "disabled": false
  }
}

克劳德的示例提示

一旦 MCP 服务器连接到 Claude，您就可以使用如下提示：

“列出我的共享文件夹中的所有电子表格”
“创建一个名为‘2024 年预算’的新电子表格”
“从我的电子表格中 ID 为 1A2B3C4D5E6F7G8H 的 Sheet1 中获取数据”
“在我的电子表格 Sheet2 的开头添加 3 行”
“使用值 [[1, 2], [3, 4]] 更新电子表格中的单元格 A1:B2”
“列出我的预算电子表格中的所有工作表”
“将‘三月’表从我的 Q1 电子表格复制到我的年度电子表格，并将其重命名为‘Q1-March’”
“在我的年度预算电子表格中添加一个名为‘Q4’的新工作表”

执照

此 MCP 服务器采用 MIT 许可证。这意味着您可以自由使用、修改和分发该软件，但须遵守 MIT 许可证的条款和条件。更多详情，请参阅项目仓库中的 LICENSE 文件。

致谢

该项目受到kazz187/mcp-google-spreadsheet存储库的启发，并使用 FastMCP 移植到 Python。

mcp-google-sheets

Integrations