Google表格MCP服务器
提供全面Google表格集成的模型上下文协议（MCP）服务器。此服务器使您能够以编程方式创建、读取、更新和管理Google表格电子表格。
🎯 目的
此服务器使您能够：
- 创建 带有自定义表格名称的新Google表格电子表格
- 阅读 电子表格中任何范围的数据
- 写 数据到特定范围
- 追加 向现有数据添加新行
- 清除 数据范围
- 获取 电子表格信息和元数据
- 批量更新 多个范围高效
🛠️ 可用工具
核心业务
- 创建电子表格
- 创建新的Google表格电子表格 - 输入： title （必填）， sheet_names （可选数组） - 返回：电子表格ID、URL和创建的表格名称
- 读取范围
- 从特定范围读取数据 - 输入： spreadsheet_id, range_name （例如，“表1！A1:C10”） - 返回：二维单元格值数组
- 写入范围
- 将数据写入特定范围（覆盖现有数据） - 输入： spreadsheet_id, range_name, values （二维阵列） - 返回：更新统计信息
- 追加行
- 将行追加到范围的末尾 - 输入： spreadsheet_id, range_name, values （二维阵列） - 返回：更新统计信息
- 清晰范围
- 清除指定范围内的所有数据 - 输入： spreadsheet_id, range_name - 返回：清除范围确认
- 获取电子表格信息
- 获取电子表格的元数据 - 输入： spreadsheet_id - 返回：标题、URL、图纸信息、尺寸
- 批量更新
- 在单个请求中执行多个范围更新 - 输入： spreadsheet_id, updates （范围/值对数组） - 返回：总更新统计信息
鼓励
- 管理工作表：用于AI助手的通用Google表格管理提示
🚀 设置
1.Google Sheets API设置
- 选择“外部”进行测试 - 将您的电子邮件添加为测试用户
- 添加OAuth作用域：
https://www.googleapis.com/auth/spreadsheets - 创建OAuth 2.0客户端ID凭据
- 选择“桌面应用程序”
- 下载凭据JSON文件
- 安全保存并记下文件路径
2.安装
使用 紫外线 （推荐）：
cd sheets-mcp-server
uv sync3.身份验证
在第一次运行时，服务器将启动一个用于OAuth身份验证的浏览器。 访问令牌将保存到指定位置 --token-path 以备将来使用。
💼 用法
独立使用
uv run sheets \
--creds-file-path /path/to/your/credentials.json \
--token-path /path/to/your/tokens.json与Claude Desktop集成
添加到您的 claude_desktop_config.json:
{
"mcpServers": {
"google-sheets": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/sheets-mcp-server",
"run",
"sheets",
"--creds-file-path",
"/path/to/your/credentials.json",
"--token-path",
"/path/to/your/tokens.json"
]
}
}
}与其他MCP客户端集成
此服务器遵循标准MCP协议，可以与任何兼容MCP的客户端集成。
📋 使用示例
创建新的电子表格
{
"tool": "create-spreadsheet",
"arguments": {
"title": "My Data Analysis",
"sheet_names": ["Data", "Analysis", "Charts"]
}
}读取数据
{
"tool": "read-range",
"arguments": {
"spreadsheet_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
"range_name": "Sheet1!A1:E10"
}
}写入数据
{
"tool": "write-range",
"arguments": {
"spreadsheet_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
"range_name": "Sheet1!A1:C3",
"values": [
["Name", "Age", "City"],
["Alice", "30", "New York"],
["Bob", "25", "San Francisco"]
]
}
}添加新数据
{
"tool": "append-rows",
"arguments": {
"spreadsheet_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
"range_name": "Sheet1!A:C",
"values": [
["Charlie", "35", "Chicago"],
["Diana", "28", "Boston"]
]
}
}批量更新
{
"tool": "batch-update",
"arguments": {
"spreadsheet_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
"updates": [
{
"range": "Sheet1!A1:B2",
"values": [["Header1", "Header2"], ["Data1", "Data2"]]
},
{
"range": "Sheet1!D1:E2",
"values": [["Header3", "Header4"], ["Data3", "Data4"]]
}
]
}
}🧪 测试
与MCP检查员一起
使用测试服务器 MCP检查员:
npx @modelcontextprotocol/inspector uv run sheets \
--creds-file-path /path/to/credentials.json \
--token-path /path/to/tokens.json手动测试
- 创建测试电子表格
- 读取一些数据 验证连接
- 写入测试数据 确保写入权限正常工作
- 尝试不同的范围格式 （A1符号、命名范围等）
📊 常见用例
数据分析工作流
1. Create spreadsheet for analysis
2. Import raw data via append-rows
3. Read data for processing
4. Write calculated results back
5. Generate reports and summaries内容管理
1. Create content tracking spreadsheet
2. Append new content entries
3. Update status and metadata
4. Generate content reports项目管理
1. Create project tracking sheet
2. Add tasks and milestones
3. Update progress and status
4. Generate project dashboards数据同步
1. Read data from external systems
2. Transform and validate data
3. Write to Google Sheets for sharing
4. Keep data synchronized across platforms🔧 高级功能
支持的范围格式
- A1符号:
Sheet1!A1:C10 - 命名范围:
MyNamedRange - 整列:
Sheet1!A:C - 整行:
Sheet1!1:5 - 开放式范围:
Sheet1!A1:C
错误处理
该服务器包括全面的错误处理功能，用于：
- 身份验证失败和令牌刷新
- 网络超时和连接问题
- 电子表格ID或范围名称无效
- 权限错误
- API配额限制
- 数据输入格式错误
性能注意事项
- 用途
asyncio.to_thread用于非阻塞API调用 - 支持批量操作以提高效率
- 优雅地处理Google Sheets API费率限制
- 针对小型和大型数据操作进行了优化
🔒 安全和权限
所需OAuth范围
https://www.googleapis.com/auth/spreadsheets-完全访问谷歌表格
安全最佳实践
- 安全地存储凭据
- 对敏感路径使用环境变量
- 实施适当的访问控制
- 定期轮换访问令牌
- 监控API使用情况和配额
🤝 贡献与扩展
此服务器设计为易于扩展。常见增强功能：
附加功能
- 格式化操作 （粗体、颜色、边框）
- 公式支持 对于计算单元格
- 图表创建 和管理
- 条件化格式 规则
- 数据验证 约束
- 数据透视表 以及总结
集成增强
- 数据库连接器 用于数据导入/导出
- CSV/Excel文件 导入导出
- 实时协作 特征
- Webhook 通知 更改
- 高级搜索 和过滤
性能优化
- 缓存策略 用于频繁访问的数据
- 流媒体支持 对于大型数据集
- 并行处理 用于批量操作
- 连接池 适用于高通量场景
📚 api参考
Google Sheets API限制
- 每位用户每100秒100个请求
- 每100秒1000个请求 （总配额）
- 最多1000万个细胞 每个电子表格
- 最多200张 每个电子表格
响应格式
所有工具返回结构化响应，包括：
- 状态指示器 （成功/错误）
- 详细的错误消息 适用时
- 更新统计 用于写入操作
- 结构化数据 用于读取操作
🆘 故障排除
常见问题
- 身份验证错误
- 验证凭据文件路径 - 检查OAuth同意屏幕配置 - 确保配置了正确的作用域
- 权限错误
- 验证电子表格共享权限 - 检查电子表格是否存在 - 确保帐户具有编辑权限
- 范围错误
- 验证A1符号格式 - 检查工作表名称是否有拼写错误 - 验证范围界限
- 超出配额
- 实现请求限制 - 尽可能使用批处理操作 - 监控Google Cloud控制台中的使用情况
______________________________________________________________________
准备好通过自动化操作来增强您的Google表格工作流程！ 🚀