Google Sheets

google-sheets-mcp

用于 Google Sheets 的 MCP 服务——读取、写入和查询电子表格数据。

使用场景

数据问题：“管道中有多少笔未结交易？”或“我们第 3 季度的总收入是多少？”→ 读取电子表格并直接回答。

快速录入费用：拍下收据照片 → 提取详细信息并在费用跟踪表中追加一行。

跨工具状态同步：“检查我们所有供应商的 Slack 频道，并用他们的最新动态更新跟踪表”→ 读取 Slack，更新工作表。

数据分析：“按地区细分 Salesforce 数据，并与我们的活动日历进行比较”→ 从多个来源提取数据到电子表格中进行分析。

（这些只是示例——任何需要电子表格数据的工作流都可以使用此服务。可与 google-drive-mcp 配合使用，以查找文件、删除文件、添加评论和管理共享权限。）

设置

1. 创建 Google OAuth 凭据

1. 前往 Google Cloud Console
2. 创建一个新项目（或使用现有项目）
3. 启用 Google Sheets API
4. 前往 APIs & Services → OAuth consent screen，设置同意屏幕
5. 前往 APIs & Services → Credentials → Create Credentials → OAuth client ID
6. 选择 Web application
7. 将 http://localhost:3000/callback 添加到 Authorized redirect URIs
8. 记下 Client ID 和 Client Secret

2. 运行服务

GOOGLE_CLIENT_ID='your-client-id' \
GOOGLE_CLIENT_SECRET='your-client-secret' \
MCP_TRANSPORT=http \
npm start

服务默认运行在 http://localhost:3000。使用 PORT=3001 更改端口。

3. 添加到 MCP 客户端

服务运行后，按照 install-mcp 上的说明操作，它会为你的 MCP 客户端（Claude Code、Claude Desktop、Cursor、Cline、VS Code 等）生成正确的配置。

架构

此服务充当 Google 的 OAuth 代理：

graph LR
    A[MCP client] <--> B[google-sheets-mcp] <--> C[Google OAuth/API]

1. 服务通过 /.well-known/oauth-authorization-server 将自身声明为 OAuth 授权服务
2. /register 返回 Google OAuth 客户端凭据
3. /authorize 重定向到 Google，并在 state 中编码客户端的回调 URL
4. /callback 接收来自 Google 的 code，并转发给客户端的回调
5. /token 将 token 请求代理到 Google，并注入客户端凭据
6. /mcp 处理 MCP 请求，使用 bearer token 调用 Google Sheets API

服务不保存任何 token 或状态——它只负责将 OAuth 请求代理到 Google。

工具

工具	描述
电子表格
sheets_spreadsheet_get	获取电子表格元数据（标题、工作表列表，可选单元格数据）
sheets_spreadsheet_create	创建新的电子表格
值
sheets_values_get	读取指定范围内的单元格值
sheets_values_batch_get	读取多个范围内的单元格值
sheets_values_update	写入指定范围内的单元格值（覆盖原有值）
sheets_values_batch_update	写入多个范围内的单元格值
sheets_values_append	在现有数据后追加行
sheets_values_clear	清除指定范围内的单元格值
工作表（标签页）
sheets_sheets_list	列出电子表格中的所有工作表
sheets_sheet_add	添加新工作表（标签页）
sheets_sheet_delete	删除工作表（标签页）
高级
sheets_batch_update	执行批量操作（格式设置、合并、筛选器等）

Google Sheets API 权限范围

• spreadsheets - 对电子表格拥有完整的读写权限

参与贡献

欢迎在 GitHub 上提交拉取请求！开始之前：

1. 安装 Git 和 Node.js
2. 克隆代码库
3. 使用 npm install 安装依赖
4. 运行 npm run test 执行测试
5. 使用 npm run build 构建

发布

版本遵循语义化版本规范。

发布步骤：

1. 使用 npm version <major | minor | patch> 更新版本号
2. 运行 git push --follow-tags 推送并附带标签
3. 等待 GitHub Actions 发布到 NPM 注册表。