A
security-
licenseA
qualityA Model Context Protocol server that provides seamless integration with Google Workspace, allowing operations with Google Drive, Docs, and Sheets through secure OAuth2 authentication.
Last updated -
8
3
MIT License
🤔 这是什么？
mcp-google-sheets是一个基于 Python 的 MCP 服务器，它充当任何兼容 MCP 的客户端（例如 Claude Desktop）和 Google Sheets API 之间的桥梁。它允许您使用一组定义的工具与 Google 电子表格进行交互，从而实现由 AI 驱动的强大自动化和数据操作工作流程。
🚀 快速入门（使用uvx ）
本质上，服务器在一行中运行： uvx mcp-google-sheets 。
此命令将根据需要自动下载并运行最新代码。但是，设置 Google Cloud 需要相当多的步骤，请阅读以下步骤。
☁️ 先决条件：Google Cloud 设置
您必须先配置 Google Cloud Platform 凭据并启用必要的 API。我们强烈建议使用服务帐号。
➡️跳转到下面的详细 Google 云平台设置指南。
🐍 安装
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" # Or using pip: # pip install uv如果需要，请按照安装程序输出中的说明将
🔑 设置必要的环境变量（建议使用服务帐户）
您需要告诉服务器如何进行身份验证。在终端中设置以下变量：
（Linux/macOS）
# Replace with YOUR actual path and folder ID from the Google Setup step export SERVICE_ACCOUNT_PATH="/path/to/your/service-account-key.json" export DRIVE_FOLDER_ID="YOUR_DRIVE_FOLDER_ID"（Windows 命令）
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）。
🏃 运行服务器！
uvx将自动下载并运行最新版本的mcp-google-sheets：uvx mcp-google-sheets服务器将启动并打印日志以表明它已准备就绪。
🔌 连接您的 MCP 客户端
配置您的客户端（例如，Claude Desktop）以连接到正在运行的服务器。
根据您使用的客户端，您可能不需要执行第 4 步，因为客户端可以自动启动服务器。但无论如何，测试运行第 4 步以确保设置正确是一个好习惯。
➡️ 有关示例，请参阅Claude Desktop 的使用方法。
您已准备好！开始通过 MCP 客户端发出命令。
✨ 主要特点
**无缝集成：**直接连接到 Google Drive 和 Google Sheets API。
**全面的工具：**提供广泛的操作（CRUD、列表、批处理、共享、格式化等）。
灵活的身份验证： 、OAuth 2.0 和通过环境变量直接注入凭证。
**轻松部署：**使用
uvx立即运行（零安装感觉）或使用uv克隆进行开发。**AI-Ready：**专为与 MCP 兼容的客户端一起使用而设计，可实现自然语言电子表格交互。
🛠️ 可用的工具和资源
该服务器公开了以下与 Google 表格交互的工具：
（除非另有说明，输入参数通常是字符串）
list_spreadsheets：列出配置的 Drive 文件夹（服务帐户）中或用户可访问的电子表格（OAuth）。*返回：*对象列表
[{id: string, title: string}]
create_spreadsheet：创建一个新的电子表格。title（字符串）：所需的标题。*返回：*包含电子表格信息的对象，包括
spreadsheetId。
get_sheet_data：从工作表的某个范围内读取数据。spreadsheet_id（字符串）sheet（字符串）：工作表的名称。range（可选字符串）：A1 格式（例如，'A1:C10'，'Sheet1!B2:D'）。如果省略，则读取整个 Sheet。*返回：*单元格值的二维数组。
update_cells：将数据写入特定范围。覆盖现有数据。spreadsheet_id（字符串）sheet（字符串）range（字符串）：A1 符号。data（二维数组）：要写入的值。*返回：*更新结果对象。
batch_update_cells：在一次 API 调用中更新多个范围。spreadsheet_id（字符串）sheet（字符串）ranges（对象）：将范围字符串（A1 符号）映射到二维值数组{ "A1:B2": [[1, 2], [3, 4]], "D5": [["Hello"]] }。*返回：*批量更新结果对象。
add_rows：将行附加到工作表的末尾（在最后一行数据之后）。spreadsheet_id（字符串）sheet（字符串）data（二维数组）：要附加的行。*返回：*更新结果对象。
list_sheets：列出电子表格中的所有工作表名称。spreadsheet_id（字符串）*返回：*工作表名称字符串列表
["Sheet1", "Sheet2"]。
create_sheet：向电子表格添加新工作表（选项卡）。spreadsheet_id（字符串）title（字符串）：新工作表的名称。*返回：*新的工作表属性对象。
get_multiple_sheet_data：一次调用即可从可能不同的电子表格的多个范围中获取数据。queries（对象数组）：每个对象都需要spreadsheet_id、sheet和range。[{spreadsheet_id: 'abc', sheet: 'Sheet1', range: 'A1:B2'}, ...]。*返回：*对象列表，每个对象包含查询参数和获取的
data或error。
get_multiple_spreadsheet_summary：获取多个电子表格的标题、工作表名称、标题和前几行。spreadsheet_ids（字符串数组）rows_to_fetch（可选整数，默认值为 5）：要预览多少行（包括标题）。*返回：*每个电子表格的摘要对象列表。
share_spreadsheet：与指定的用户/电子邮件和角色共享电子表格。spreadsheet_id（字符串）recipients（对象数组）：[{email_address: 'user@example.com', role: 'writer'}, ...]。角色：reader，commenter，writer。send_notification（可选布尔值，默认 True）：发送电子邮件通知。*返回：*包含
successes和failures列表的字典。
add_columns：向工作表添加列。 （如果已实现，请验证参数）copy_sheet：复制电子表格中的工作表。 （如果已实现，请验证参数）rename_sheet：重命名现有工作表。 （如果已实现，请验证参数）
MCP 资源：
spreadsheet://{spreadsheet_id}/info：获取有关 Google 电子表格的基本元数据。*返回：*包含电子表格信息的 JSON 字符串。
☁️ Google 云平台设置（详细）
运行服务器之前需要进行此设置。
**创建/选择 GCP 项目：**转到Google Cloud Console 。
**启用 API：**前往“API 和服务”->“库”。搜索并启用：
Google Sheets APIGoogle Drive API
**配置凭据：**您需要选择以下一种身份验证方法（建议使用服务帐户）。
🔑 身份验证和环境变量（详细）
服务器需要凭据才能访问 Google API。请选择一种方法：
方法 A：服务帐户（推荐用于服务器/自动化）✅
**为什么？**无头（无需浏览器）、安全，非常适合服务器环境。而且不会轻易过期。
步骤：
**创建服务帐户：**在 GCP 控制台 -> “IAM 和管理” -> “服务帐户”。
点击“+ 创建服务帐户”。为其命名（例如，
mcp-sheets-service）。授予角色：添加
Editor角色以获得广泛访问权限，或添加更细粒度的角色（如roles/drive.file和特定的 Sheets 角色）以获得更严格的权限。点击“完成”。找到该账户，点击“操作”(⋮) -> “管理密钥”。
点击“添加密钥”->“创建新密钥”-> JSON ->“创建”。
下载并安全存储JSON 密钥文件。
创建并共享 Google Drive 文件夹：
在Google Drive中，创建一个文件夹（例如“AI Managed Sheets”）。
记下 URL 中的文件夹 ID ：
https://drive.google.com/drive/folders/THIS_IS_THE_FOLDER_ID。右键点击文件夹->“共享”->“共享”。
输入服务帐户的电子邮件（来自 JSON 文件
client_email）。授予编辑权限。取消勾选“通知他人”。点击“共享”。
设置环境变量：
SERVICE_ACCOUNT_PATH：下载的 JSON 密钥文件的完整路径。DRIVE_FOLDER_ID：共享 Google Drive 文件夹的 ID。 （请参阅
方法 B：OAuth 2.0（交互式/个人使用）🧑💻
**为什么？**因为对于个人使用或本地开发来说，交互式浏览器登录是可以的。
步骤：
**配置 OAuth 授权界面：**在 GCP Console -> “API 和服务” -> “OAuth 授权界面” 中选择“外部”，填写所需信息，添加授权范围（
.../auth/spreadsheets，.../auth/drive），并根据需要添加测试用户。**创建 OAuth 客户端 ID：**在 GCP Console -> “API 和服务” -> “凭据”。“+ 创建凭据” -> “OAuth 客户端 ID” -> 类型：桌面应用。将其命名为“CREATE”。下载 JSON 文件。
设置环境变量：
CREDENTIALS_PATH：下载的 OAuth 凭据 JSON 文件的路径（默认值：credentials.json）。TOKEN_PATH：用户首次登录后存储刷新令牌的路径（默认值：token.json）。必须可写。
方法 C：直接凭证注入（高级）🔒
**为什么？**在 Docker、Kubernetes 或 CI/CD 等环境中很有用，因为这些环境中文件管理比较困难，但环境变量却很容易/安全。避免访问文件系统。
**怎么做呢？**您无需提供凭证文件的路径，而是直接在环境变量中提供以 Base64 编码的文件内容。
步骤：
获取您的凭证 JSON 文件（服务帐户密钥或 OAuth 客户端 ID 文件）。我们将其命名为
your_credentials.json。生成Base64字符串：
（Linux/macOS）：
base64 -w 0 your_credentials.json（Windows PowerShell）：
$filePath = "C:\path\to\your_credentials.json"; # Use actual path $bytes = [System.IO.File]::ReadAllBytes($filePath); $base64 = [System.Convert]::ToBase64String($bytes); $base64 # Copy this output**（警告）：**避免将敏感凭证粘贴到不受信任的在线编码器中。
设置环境变量：
CREDENTIALS_CONFIG：将此变量设置为您刚刚生成的完整 Base64 字符串。# Example (Linux/macOS) - Use the actual string generated export CREDENTIALS_CONFIG="ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb..."
身份验证优先级和摘要
服务器按以下顺序检查凭证：
CREDENTIALS_CONFIG（Base64 内容）SERVICE_ACCOUNT_PATH（服务帐户 JSON 的路径）CREDENTIALS_PATH（OAuth JSON 路径）- 如果令牌丢失或过期，则触发交互流程。
环境变量摘要：
多变的 | 方法） | 描述 | 默认 |
| 服务帐户 | 服务帐户 JSON 密钥文件的路径。 | - |
| 服务帐户 | 与服务帐户共享的 Google Drive 文件夹的 ID。 | - |
| OAuth 2.0 | OAuth 2.0 客户端 ID JSON 文件的路径。 |
|
| OAuth 2.0 | 存储生成的 OAuth 令牌的路径。 |
|
| 服务帐户/OAuth 2.0 | 凭证内容的 Base64 编码 JSON 字符串。 | - |
⚙️ 运行服务器（详细）
方法一：使用uvx （推荐用户）
如超级快速入门中所示，这是最简单的方法。设置环境变量，然后运行：
uvx mcp-google-sheets
uvx临时处理获取和运行包。
方法 2：用于开发（克隆 Repo）
如果要修改代码：
克隆：
git clone https://github.com/yourusername/mcp-google-sheets.git && cd mcp-google-sheets（使用实际 URL）**设置环境变量：**如上所述。
**使用
uv运行：（**使用本地代码）uv run mcp-google-sheets # Or via the script name if defined in pyproject.toml, e.g.: # uv run start
🔌 与 Claude Desktop 一起使用
将服务器配置添加到mcpServers下的claude_desktop_config.json中。选择与你的设置匹配的块：
{
"mcpServers": {
"google-sheets": {
"command": "uvx",
"args": ["mcp-google-sheets"],
"env": {
// Use ABSOLUTE paths here
"SERVICE_ACCOUNT_PATH": "/full/path/to/your/service-account-key.json",
"DRIVE_FOLDER_ID": "your_shared_folder_id_here"
},
"healthcheck_url": "http://localhost:8000/health" // Adjust host/port if needed
}
}
}
{
"mcpServers": {
"google-sheets": {
"command": "uvx",
"args": ["mcp-google-sheets"],
"env": {
// Use ABSOLUTE paths here
"CREDENTIALS_PATH": "/full/path/to/your/credentials.json",
"TOKEN_PATH": "/full/path/to/your/token.json" // Ensure this path is writable
},
"healthcheck_url": "http://localhost:8000/health"
}
}
}
（首次使用时，浏览器可能会打开 Google 登录）
{
"mcpServers": {
"google-sheets": {
"command": "uvx",
"args": ["mcp-google-sheets"],
"env": {
// Paste the full Base64 string here
"CREDENTIALS_CONFIG": "ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb3VudCIsCiAgInByb2plY3RfaWQiOiAi...",
"DRIVE_FOLDER_ID": "your_shared_folder_id_here" // Still needed for Service Account folder context
},
"healthcheck_url": "http://localhost:8000/health"
}
}
}
{
"mcpServers": {
"mcp-google-sheets-dev": { // Use a distinct name
"command": "uv",
"args": ["run", "mcp-google-sheets"], // Assumes `mcp-google-sheets` script exists
"cwd": "/full/path/to/cloned/mcp-google-sheets", // ABSOLUTE path to repo
"env": {
// Choose ONE auth method and set corresponding vars
// Example: Service Account Path
"SERVICE_ACCOUNT_PATH": "/full/path/to/cloned/mcp-google-sheets/service-account-key.json",
"DRIVE_FOLDER_ID": "your_shared_folder_id_here"
},
"healthcheck_url": "http://localhost:8000/health",
"disabled": false
}
}
}
💬 Claude 的示例提示
连接后，尝试如下提示：
“列出我有权访问的所有电子表格。”（或“在我的 AI 管理表格文件夹中”）
“创建一个名为‘2024 年第三季度季度销售报告’的新电子表格。”
“在‘季度销售报告’电子表格中，获取 Sheet1 范围 A1 至 E10 中的数据。”
“向 ID 为
1aBcDeFgHiJkLmNoPqRsTuVwXyZ电子表格中添加一个名为‘Summary’的新工作表。”“在我的‘项目任务’电子表格的‘任务’表中，将单元格 B2 更新为‘进行中’。”
“将这些行附加到电子表格
XYZ中的‘日志’表：[['2024-07-31', 'Task A Completed'], ['2024-08-01', 'Task B Started']]”“获取电子表格‘销售数据’和‘库存数量’的摘要。”
将‘团队休假计划’电子表格分享给
team@example.com（读者）和manager@example.com（撰写者）。不发送通知。
🤝 贡献
欢迎贡献！请提交问题来讨论错误或功能请求。欢迎提交拉取请求。
📄 许可证
该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅LICENSE文件。
🙏 致谢
使用FastMCP构建。
使用 Google API Python 客户端库。
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
与 Google Drive 和 Google Sheets 集成的模型上下文协议服务器，使用户能够通过自然语言命令创建、读取、更新和管理电子表格。
Related MCP Servers
- Asecurity-licenseAqualityProvides a Model Context Protocol (MCP) server that enables LLMs to directly access and interact with Google Spreadsheet data.Last updated -21
- Asecurity-licenseAqualityA Model Context Protocol server that enables AI agents to interact with Google Workspace services including Drive, Docs, and Sheets through natural language commands.Last updated -8MIT License
- Asecurity-licenseAqualityA Model Context Protocol server that provides an interface for AI models to interact with Google Docs, enabling reading, creating, updating, and searching Google Documents.Last updated -43