项目简介

本项目是一个基于 Model Context Protocol (MCP) 的服务器实现，专注于集成 Google Sheets。它允许大型语言模型 (LLM) 客户端通过标准化的 MCP 协议，安全、便捷地访问和操作 Google Sheets 中的电子表格数据。该服务器提供了一系列工具，使 LLM 能够创建、读取、更新和管理电子表格，从而扩展 LLM 在数据处理和分析方面的能力。

主要功能点

数据读取与写入: 支持从 Google Sheets 中读取指定范围的数据，并将数据更新回电子表格。
批量操作: 支持批量更新多个单元格区域，以及批量获取多个表格数据，提高数据处理效率。
电子表格管理: 提供创建新的电子表格和工作表，列出电子表格和工作表，复制和重命名工作表等管理功能。
权限管理: 支持通过邮件分享电子表格给指定用户，并分配不同的访问权限（读者、评论者、作者）。
多种认证方式: 支持服务账号和 OAuth 2.0 两种认证方式，适应不同场景的需求。服务账号认证适合服务器环境，OAuth 2.0 适合个人开发和交互式使用。
资源访问: 提供资源接口，可以获取电子表格的基本信息。

安装步骤

Google Cloud Platform 设置 (所有方法都需要):
- 访问 Google Cloud Console，创建一个新的 GCP 项目或选择现有项目。
- 在项目中启用 Google Sheets API 和 Google Drive API。
选择认证方式 (二选一):

方法 1: 服务账号认证 (推荐)
- 访问 Google Cloud Console -> IAM & 管理 -> 服务账号。
- 创建一个新的服务账号，并授予适当的角色（例如 Google Sheets 的访问权限）。
- 创建并下载 JSON 密钥文件。
- 在 Google Drive 中创建一个专门的文件夹，用于存放由该 MCP 服务器管理的电子表格（例如 "LLM Sheets"）。
- 记录该文件夹的 文件夹 ID （URL 中 'folders/' 后面的部分）。
- 将该文件夹共享给服务账号的邮件地址（在 JSON 密钥文件中 'client_email' 字段）。授予 "编辑者" 权限。
方法 2: OAuth 2.0 认证 (交互式)
- 配置 OAuth 同意屏幕。
- 创建 OAuth 2.0 客户端 ID 凭据 (应用类型选择 桌面应用)。
- 下载凭据 JSON 文件，并保存为 'credentials.json' (默认文件名)。

设置环境变量:

根据选择的认证方式，设置以下环境变量。

服务账号认证:

export SERVICE_ACCOUNT_PATH=/path/to/your/service-account-key.json  # 替换为您的服务账号密钥文件路径
export DRIVE_FOLDER_ID=your_shared_folder_id_here       # 替换为您共享文件夹的 ID

OAuth 2.0 认证:

export CREDENTIALS_PATH=/path/to/your/credentials.json   # 替换为您的 OAuth 凭据文件路径
export TOKEN_PATH=token.json                          # (可选) 令牌文件保存路径，默认为 token.json

注意: 请将 '/path/to/your/...' 和 'your_shared_folder_id_here' 替换为实际的文件路径和文件夹 ID。

服务器配置

将以下 JSON 配置添加到您的 MCP 客户端配置文件（例如 'claude_desktop_config.json'）的 'mcpServers' 字段中。根据您的认证方式选择相应的配置：

使用 uvx 运行 (推荐，服务账号认证):

"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"      // 替换为您共享文件夹的 ID
  }
}

使用 uvx 运行 (OAuth 认证):

"google-sheets": {
  "command": "uvx",
  "args": ["mcp-google-sheets"],
  "env": {
    "CREDENTIALS_PATH": "/path/to/your/credentials.json", // 替换为您的 OAuth 凭据文件路径
    "TOKEN_PATH": "token.json"                         // (可选) 令牌文件保存路径，默认为 token.json
  }
}

开发模式运行 (方便修改代码):

"mcp-google-sheets": {
  "command": "uv",
  "args": [
    "--directory",
    "/path/to/mcp-google-sheets", // 替换为 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"      // 替换为您共享文件夹的 ID
    // OR for OAuth:
    // "CREDENTIALS_PATH": "/path/to/mcp-google-sheets/credentials.json", // 替换为您的 OAuth 凭据文件路径 (或相对路径)
    // "TOKEN_PATH": "/path/to/mcp-google-sheets/token.json"         // (可选) 令牌文件保存路径，默认为 token.json (或相对路径)
  },
  "disabled": false
}

基本使用方法

配置完成后，在支持 MCP 协议的 LLM 客户端中，即可通过自然语言指令调用 Google Sheets 的功能。以下是一些示例指令：

"列出我共享文件夹中的所有电子表格"
"创建一个名为 '2024年预算' 的新电子表格"
"获取 ID 为 1A2B3C4D5E6F7G8H 的电子表格中 Sheet1 的数据"
"在我的预算电子表格中 Sheet2 的开头添加 3 行"
"将我的电子表格中 A1:B2 单元格更新为 [[1, 2], [3, 4]]"
"列出我的预算电子表格中的所有工作表"
"获取我的 '项目跟踪' 和 '团队名册' 电子表格的摘要"
"从电子表格 'proj-abc' 的 'Tasks!A1:E10' 范围和电子表格 'roster-xyz' 的 'Sheet1!B2:B' 范围获取数据"
"将我的 'Q3 计划' 电子表格以写入者身份分享给 [email protected]，以读者身份分享给 [email protected]"

关键词

项目简介

主要功能点

安装步骤

服务器配置

基本使用方法

信息