Google表格MCP服务器
一种模型上下文协议（MCP）服务器，在兼容MCP的客户端（如Claude Desktop）和Google Sheets API之间提供安全的桥梁。
](https://www.docker.com/)  
概述
此MCP服务器为人工智能助手提供了一个安全的接口，使其能够与谷歌电子表格进行交互，从而实现强大的自动化和数据操作工作流程。它支持服务帐户和OAuth 2.0身份验证方法，并作为容器化服务运行，以增强安全性。
主要特点
- 31工具 用于全面的电子表格操作
- 服务帐户和OAuth 2.0 身份验证支持
- 基于Docker 非root用户执行的部署
- 表级操作 用于结构化数据管理
- 批量操作 用于高效使用API
- 条件化格式 使用自定义规则和公式
- CSV导入/导出 能力
建筑
Claude Desktop → MCP Gateway → Google Sheets Server → Google Sheets API
↓
Docker Desktop Secrets可用工具
电子表格管理（3个工具）
list_spreadsheets-从Drive文件夹或用户访问中列出电子表格create_spreadsheet-创建新的电子表格share_spreadsheet-与用户/电子邮件共享（读者、评论者、作家角色）
表格操作（6个工具）
list_sheets-在电子表格中列出所有工作表名称create_sheet-添加新工作表（选项卡）rename_sheet-重命名现有图纸copy_sheet-在电子表格内或跨电子表格复制表格add_columns-在工作表中添加列add_conditional_formatting-添加条件格式规则update_conditional_formatting-更新或移动现有规则
数据访问（4个工具）
get_sheet_data-从范围读取数据（带可选网格元数据）get_sheet_formulas-从范围中读取公式get_multiple_sheet_data-在一次调用中获取多个范围get_multiple_spreadsheet_summary-获取标题、页眉和预览行
数据修改（3个工具）
update_cells-将数据写入特定范围（覆盖）batch_update_cells-在一次呼叫中更新多个范围add_rows-将行附加到工作表末尾
表操作（11个工具）
list_tables-列出定义的表（命名范围）create_table-创建带有标题和可选数据的表get_table_data-使用过滤器、限制、偏移读取表数据insert_table_rows-在表中插入行update_table_rows-更新符合条件的行delete_table_rows-删除符合条件的行add_table_columns-向表中添加列rename_table_column-重命名表头export_table_as_csv-将表格导出为CSV格式import_csv_to_table-将CSV内容导入表中
先决条件
- 启用MCP工具包的Docker桌面
- Docker MCP CLI插件(
docker mcp命令） - 谷歌云项目：
- 已启用Google Sheets API - 已启用Google Drive API
- 资格证书：
- 服务帐户JSON文件（推荐），或 - 用于用户身份验证的OAuth 2.0凭据
快速开始
1.构建Docker镜像
git clone
cd MCP_GoogleSheets
docker build -t googlesheets-mcp-server .2.配置凭据
# Service Account (recommended)
docker mcp secret set GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"
docker mcp secret set SERVICE_ACCOUNT_EMAIL="your-sa@project.iam.gserviceaccount.com"
# Optional: Specify default Drive folder
docker mcp secret set DRIVE_FOLDER_ID="your-folder-id"3.创建自定义目录
创建或编辑 ~/.docker/mcp/catalogs/custom.yaml:
version: 2
name: custom
displayName: Custom MCP Servers
registry:
googlesheets:
description: "Bridge between MCP clients and Google Sheets API"
title: "Google Sheets"
type: server
dateAdded: "2025-10-11T00:00:00Z"
image: googlesheets-mcp-server:latest
ref: ""
tools:
- name: list_spreadsheets
- name: create_spreadsheet
- name: get_sheet_data
# ... (see readme.txt for complete list)
secrets:
- name: GOOGLE_APPLICATION_CREDENTIALS
env: GOOGLE_APPLICATION_CREDENTIALS
- name: SERVICE_ACCOUNT_EMAIL
env: SERVICE_ACCOUNT_EMAIL
- name: DRIVE_FOLDER_ID
env: DRIVE_FOLDER_ID
metadata:
category: productivity
tags: [google, sheets, spreadsheet, data]4.更新注册表
编辑 ~/.docker/mcp/registry.yaml 并添加：
registry:
googlesheets:
ref: ""5.配置克劳德桌面
编辑您的Claude Desktop配置文件：
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - 视窗:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
将自定义目录添加到args数组：
{
"mcpServers": {
"mcp-toolkit-gateway": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-v", "/var/run/docker.sock:/var/run/docker.sock",
"-v", "/Users/your_username/.docker/mcp:/mcp",
"docker/mcp-gateway",
"--catalog=/mcp/catalogs/docker-mcp.yaml",
"--catalog=/mcp/catalogs/custom.yaml",
"--config=/mcp/config.yaml",
"--registry=/mcp/registry.yaml",
"--tools-config=/mcp/tools.yaml",
"--transport=stdio"
]
}
}
}6.重新启动克劳德桌面
退出并完全重新启动Claude Desktop。您的Google表格工具现在应该可用了！
使用示例
基本操作
"List all my spreadsheets"
"Create a new spreadsheet called 'Q1 Sales Data 2025'"
"Get data from Sheet1 range A1:D10 in spreadsheet [ID]"
"Add a new sheet called 'Revenue' to my spreadsheet"表操作
"Create a table with headers ['Name', 'Email', 'Status'] in Sheet1"
"Get all data from the 'Customers' table where Status is 'Active'"
"Insert rows [['John', 'john@example.com', 'Active']] into the Users table"
"Export the 'Sales' table as CSV"高级功能
"Share my spreadsheet with user@example.com as a writer"
"Add conditional formatting to highlight values > 100 in A1:D10"
"Update cells A1:B2 with data [[1,2],[3,4]]"
"Batch update multiple ranges: A1:B2 and D5:E6"数据格式示例
2D数组（用于update_cells、add_rows）
[["Header1", "Header2"], ["Value1", "Value2"]]多个范围（用于batch_update_cells）
{"A1:B2": [[1, 2], [3, 4]], "D5": [["Hello"]]}过滤器（用于get_table_data）
{"Status": "Active", "Country": "USA"}条件格式规则
{
"type": "boolean",
"condition": {
"type": "NUMBER_GREATER",
"values": [{"userEnteredValue": "100"}]
},
"format": {
"backgroundColor": {"red": 1.0, "green": 0.8, "blue": 0.8},
"textFormat": {"bold": true}
}
}发展
局部测试
# Set environment variables
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"
# Run server
python googlesheets_server.py
# Test MCP protocol
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python googlesheets_server.py添加新工具
- 添加功能
googlesheets_server.py - 用…装饰
@mcp.tool() - 使用 仅限单行docstring
- 使用空字符串默认值(
param: str = "") - 始终返回字符串
- 使用新工具名称更新目录
- 重建Docker镜像
实施细则
看 CLAUDE.md 有关详细指南：
- 无多行文档字符串（导致网关死机）
- 打字模块没有类型提示
- 不
None默认值（使用""相反） - 仅限单行文档字符串
- 始终从工具返回字符串
故障排除
工具未出现
# Check Docker image
docker images | grep googlesheets
# Verify server in list
docker mcp server list
# Check logs
docker logs [container_name]身份验证错误
# Verify secrets
docker mcp secret list
# Check APIs enabled in Google Cloud Console:
# - Google Sheets API
# - Google Drive API常见问题
- 网关恐慌：检查工具中的多行文档字符串
- JSON解析错误：确保使用双引号的JSON有效
- 空结果：验证电子表格ID、工作表名称和范围符号
安全
- 存储在Docker Desktop机密中的凭据（从未硬编码）
- 服务器以非root用户身份运行(
mcpuser) - 从未记录敏感数据
- 仅在授权的电子表格上操作
API限值
Google Sheets API配额：
- 每个项目每100秒500个请求
- 每位用户每100秒100个请求
考虑实现用于生产的请求批处理和缓存。
文件
googlesheets_server.py-主MCP服务器实现Dockerfile-容器定义requirements.txt-Python依赖关系readme.txt-详细的安装指南CLAUDE.md-克劳德代码开发指南mcp-builder-prompt.md-用于构建此服务器的模板提示
参考文献
许可证
MIT许可证
支持
对于问题和疑问：
- 检查 故障排除 章节
- 审查
readme.txt有关详细的设置说明 - 看
CLAUDE.md实施指南 - 检查Docker日志：
docker logs [container_name]