mcp-google-sheets: 一个 Google Sheets MCP 服务器

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

概述

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

工具

1. get_sheet_data

   • 从 Google 电子表格中的特定工作表中获取数据
   • 输入：
     • spreadsheet_id (字符串): 电子表格的 ID（在 URL 中找到）
     • sheet (字符串): 工作表的名称
     • range (可选字符串): A1 表示法中的单元格范围（例如，'A1:C10'）
   • 返回：工作表数据的二维数组

2. update_cells

   • 更新 Google 电子表格中的单元格
   • 输入：
     • spreadsheet_id (字符串): 电子表格的 ID
     • sheet (字符串): 工作表的名称
     • range (字符串): A1 表示法中的单元格范围
     • data (二维数组): 要更新的值
   • 返回：更新操作的结果

3. batch_update_cells

   • 批量更新 Google 电子表格中的多个范围
   • 输入：
     • spreadsheet_id (字符串): 电子表格的 ID
     • sheet (字符串): 工作表的名称
     • ranges (对象): 将范围字符串映射到值二维数组的字典
   • 返回：批量更新操作的结果

4. list_sheets

   • 列出 Google 电子表格中的所有工作表
   • 输入：
     • spreadsheet_id (字符串): 电子表格的 ID
   • 返回：工作表名称列表

5. list_spreadsheets

   • 列出配置的 Google Drive 文件夹中的所有电子表格
   • 返回：包含 ID 和标题的电子表格列表
   • 注意：如果使用服务帐户身份验证，这将列出共享文件夹中的电子表格

6. create_spreadsheet

   • 创建新的 Google 电子表格
   • 输入：
     • title (字符串): 新电子表格的标题
   • 返回：有关新创建的电子表格的信息，包括其 ID
   • 注意：当使用配置了文件夹 ID 的服务帐户身份验证时，电子表格将在该文件夹中创建

7. create_sheet

   • 在现有 Google 电子表格中创建一个新的工作表标签
   • 输入：
     • spreadsheet_id (字符串): 电子表格的 ID
     • title (字符串): 新工作表的标题
   • 返回：有关新创建的工作表的信息

8. 附加工具：add_rows、add_columns、copy_sheet、rename_sheet

资源

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

安装和设置

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

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

1. 创建一个 Google Cloud Platform 项目：
   • 转到 Google Cloud Console
   • 创建一个新项目或选择一个现有项目
   • 启用 Google Sheets API 和 Google Drive API

选择一种身份验证方法

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

方法 1：服务帐户身份验证（推荐，非交互式）

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

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

设置步骤：

1. 创建一个服务帐户：

   • 转到 Google Cloud Console → IAM & 管理 → 服务帐户
   • 创建一个具有描述性名称的新服务帐户
   • 授予它适当的角色（用于 Google Sheets 访问）
   • 创建并下载 JSON 密钥文件

2. 在 Google Drive 中创建一个专用文件夹，与服务帐户共享：

   • 转到 Google Drive 并创建一个新文件夹（例如，“Claude Sheets”）
   • 从其 URL 中记下文件夹的 ID：https://drive.google.com/drive/folders/FOLDER_ID_HERE
   • 右键单击该文件夹并选择“共享”
   • 与服务帐户电子邮件地址共享它（在 JSON 文件中找到为 client_email）
   • 授予它“编辑者”访问权限

3. 设置以下环境变量：

   • SERVICE_ACCOUNT_PATH：服务帐户 JSON 密钥文件的路径
   • DRIVE_FOLDER_ID：与服务帐户共享的 Google Drive 文件夹的 ID

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

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

1. 为您的项目配置 OAuth：

   • 配置 OAuth 同意屏幕
   • 创建 OAuth 2.0 客户端 ID 凭据（桌面应用程序类型）
   • 下载凭据 JSON 文件并将其另存为 credentials.json

2. 设置以下环境变量：

   • CREDENTIALS_PATH：下载的 OAuth 凭据文件的路径（默认值：credentials.json）
   • TOKEN_PATH：将存储身份验证令牌的路径（默认值：token.json）

设置环境变量

对于 Linux/Mac：

# 对于服务帐户身份验证（推荐）
export SERVICE_ACCOUNT_PATH=/path/to/your/service-account-key.json
export DRIVE_FOLDER_ID=your_shared_folder_id_here

# 或者对于 OAuth 身份验证
export CREDENTIALS_PATH=/path/to/your/credentials.json
export TOKEN_PATH=/path/to/your/token.json

对于 Windows：

# 对于服务帐户身份验证（推荐）
set SERVICE_ACCOUNT_PATH=C:\path\to\your\service-account-key.json
set DRIVE_FOLDER_ID=your_shared_folder_id_here

# 或者对于 OAuth 身份验证
set CREDENTIALS_PATH=C:\path\to\your\credentials.json
set TOKEN_PATH=C:\path\to\your\token.json

运行服务器

方法 1：使用 uvx（推荐用于正常使用）

当使用 uvx 时，您可以直接运行服务器而无需安装：

# 首先设置环境变量，然后运行服务器
uvx mcp-google-sheets

方法 2：用于开发和修改

如果您想修改和开发服务器：

1. 克隆存储库：

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

2. 使用 uv 运行：

# 首先设置环境变量，然后运行
uv run mcp-google-sheets

身份验证过程

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

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

使用服务帐户身份验证，无需浏览器交互，服务器将直接在共享的 Google Drive 文件夹中的电子表格上运行。

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

与 Claude Desktop 一起使用

将其添加到您的 claude_desktop_config.json：

<details> <summary>使用 uvx 和服务帐户身份验证（推荐）</summary>

"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"
    }
  }
}

</details>

<details> <summary>使用 uvx 和 OAuth 身份验证</summary>

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

</details>

<details> <summary>用于开发</summary>

"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
  }
}

</details>

Claude 的示例提示

将 MCP 服务器连接到 Claude 后，您可以使用如下提示：

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

许可证

此 MCP 服务器已获得 MIT 许可证的许可。 这意味着您可以自由使用、修改和分发该软件，但须遵守 MIT 许可证的条款和条件。 有关更多详细信息，请参阅项目存储库中的 LICENSE 文件。

鸣谢

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