内容
# maru-sheets-mcp
MCP 服务器允许 AI 代理通过 API v4 读取/写入/格式化 Google Sheets。
---
## 👩💼 用户指南
您不需要了解代码。只需打开 Antigravity 2.0（或其他 AI 编程代理），**粘贴以下提示**，然后按照 AI 的指示操作。
### 将以下提示粘贴到 Antigravity 2.0 中：
```
我需要您安装 MCP 服务器 "maru-sheets-mcp"，以便我可以从这里读取和写入 Google Sheets。
在存储库 https://github.com/leaddaruma-web/maru-sheets-mcp 中阅读 README.md 文件 - 特别是 "用户指南" 部分，它提供了每一步的详细说明。
请为我完成所有步骤 - 包括检查/安装 Node.js（如果计算机上尚未安装）。
请指导我根据 README 中的步骤 2 在 Google Cloud 上创建 credentials.json 文件。
我只需要点击 "允许" 当浏览器打开并请求 Gmail 权限时。
开始吧。
```
然后，AI 将自动完成所有操作。您只需要：
- **当浏览器打开并请求 Gmail 权限时，点击 "允许"**（仅一次）
- **在 AI 要求时重启 Antigravity**（如果 AI 需要）
### 安装完成后，您可以要求 AI：
- *"从 Sheet [粘贴 Sheet 链接] 的 '日志' 标签页读取数据，列 A 到 K"*
- *"将以下列表写入 Sheet [粘贴 Sheet 链接]，从单元格 A2 开始：..."*
- *"在 Sheet [粘贴 Sheet 链接] 中创建新的标签页 '7 月'"*
- *"格式化 header：绿色背景，白色文字，加粗"*
- *"在单元格 B101 处设置计算列 B 总和的公式"*
### 注意
- **Sheet 必须与您的 Gmail 地址共享** - 如果 AI 报告 "insufficient permission"，请打开 Sheet → 点击 Share → 添加您的 Gmail 地址（编辑权限）
- **只需安装一次** - 以后打开 Antigravity 即可使用
---
## 🤖 AI 编程代理指南
> 本部分内容供 AI 代理阅读和执行。用户无需阅读本部分。
### 步骤 0 - 检查和安装 Node.js（如果尚未安装）
```bash
node --version
```
如果上述命令报错或版本 < 18，请安装 Node.js：
- **Windows**：从 https://nodejs.org/en/download/ 下载并运行安装程序（选择 LTS 版本，运行 .msi 文件，选择所有默认设置）。安装完成后，需要打开新的终端窗口才能使 `node` 命令生效。
- **macOS**：`brew install node` 或从 https://nodejs.org/ 下载安装程序
- **Linux**：`curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - && sudo apt-get install -y nodejs`
安装完成后，请再次检查：
```bash
node --version # 必须 >= 18
npm --version # 必须存在
```
### 步骤 1 - 克隆存储库
```bash
git clone https://github.com/leaddaruma-web/maru-sheets-mcp.git
cd maru-sheets-mcp
```
如果计算机上尚未安装 git：
- **Windows**：从 https://git-scm.com/download/win 下载，默认安装
- **macOS**：`xcode-select --install`
- **Linux**：`sudo apt-get install git`
### 步骤 2 - 创建 credentials.json 文件
此文件包含 OAuth 客户端信息 - **存储库中不包含（出于安全考虑）**。用户需要在 Google Cloud 上自行创建（免费）。
**通知用户：** "您需要在 Google Cloud 上创建 credentials - 免费，仅需 3 分钟。我将指导您完成每一步，您只需按照提示操作即可。"
指导用户打开浏览器并按照以下步骤操作：
**步骤 2.1. 创建 Google Cloud 项目：**
- 打开 https://console.cloud.google.com/
- 使用将用于读取/写入 Sheet 的 Gmail 地址登录
- 点击顶部菜单栏中的项目下拉菜单（Google Cloud 徽标旁边）→ "新建项目"
- 为项目命名：`maru-sheets-mcp` → 点击 "创建"
- 等待几秒钟，选择刚刚创建的项目
**步骤 2.2. 启用 Google Sheets API：**
- 打开 https://console.cloud.google.com/apis/library/sheets.googleapis.com
- 点击 "启用"
- 另外打开 https://console.cloud.google.com/apis/library/drive.googleapis.com
- 点击 "启用"
**步骤 2.3. 配置 OAuth 同意屏幕：**
- 打开 https://console.cloud.google.com/apis/credentials/consent
- 选择 "外部" → 点击 "创建"
- 填写：
- 应用名称：`maru-sheets-mcp`
- 用户支持邮箱：选择您的 Gmail 地址
- 开发人员联系方式：输入您的 Gmail 地址
- 点击 "保存并继续" 跳过剩余的步骤（作用域，测试用户）→ 点击 "返回仪表盘"
- 在同意屏幕页面，点击 "发布应用" 如果您计划长期使用（如果只是测试，请跳过）
**步骤 2.4. 创建 OAuth 客户端 ID：**
- 打开 https://console.cloud.google.com/apis/credentials
- 点击 "+ 创建凭证" → "OAuth 客户端 ID"
- 应用类型：选择 **"桌面应用"**
- 名称：`maru-sheets-mcp`
- 点击 "创建"
- **屏幕上会显示客户端 ID 和客户端密钥** - 复制这两个值
**步骤 2.5. 创建 credentials.json 文件：**
在存储库根目录（`maru-sheets-mcp/credentials.json`）创建 `credentials.json` 文件，内容如下：
```json
{
"installed": {
"client_id": "替换为客户端 ID",
"project_id": "maru-sheets-mcp",
"client_secret": "替换为客户端密钥",
"auth_uri": "https://accounts.google.com/o/oauth2/auth",
"token_uri": "https://oauth2.googleapis.com/token",
"redirect_uris": ["http://localhost:4571/oauth2callback"]
}
}
```
用步骤 4 中复制的值替换 `替换为客户端 ID` 和 `替换为客户端密钥`。
**通知用户：** "完成凭证创建步骤！请继续安装。"
### 步骤 3 - 安装依赖项
```bash
npm install
```
### 步骤 4 - Gmail 授权（仅一次）
```bash
npm run auth
```
此命令将：
1. 在 Google 授权 URL 打开浏览器
2. 用户登录 Gmail 并点击 "允许" / "允许"
3. 浏览器重定向到 localhost → 自动创建 `token.json` 文件
**通知用户：** "浏览器将打开 - 您请登录 Gmail 然后点击允许。"
等待终端显示 `✓ 已保存 token.json` 然后继续。
### 步骤 5 - 配置 MCP 服务器
记住克隆的 `maru-sheets-mcp` 存储库的绝对路径（例如 `D:\Projects\maru-sheets-mcp` 或 `/Users/username/maru-sheets-mcp`）。
将以下内容添加到正在使用的工具的 MCP 配置文件中：
**Claude Code** - `claude_desktop_config.json` 或 `.claude.json` 文件：
```json
{
"mcpServers": {
"maru-sheets": {
"command": "node",
"args": ["src/sheets-server.js"],
"cwd": "<绝对路径到 maru-sheets-mcp 存储库>"
}
}
}
```
**Antigravity 2.0** - 进入设置 → MCP 服务器 → 添加新服务器：
- 名称：`maru-sheets`
- 命令：`node`
- 参数：`src/sheets-server.js`
- 工作目录：`<绝对路径到 maru-sheets-mcp 存储库>`
**其他工具** - 类似地，将命令设置为 `node`，参数设置为 `src/sheets-server.js`，工作目录设置为包含存储库的目录。
### 步骤 6 - 测试
配置完成后，重启工具（或重新加载 MCP）并测试：
- 调用 `list_sheets` 工具，传入任意 `spreadsheetId`（您已授权的 Gmail 地址有权访问的）
- 如果返回标签页列表 → **成功**
**通知用户：** "安装完成！您可以重启 Antigravity 然后尝试让我读取/写入 Sheet。"
### 安装后可用的工具
| 工具 | 描述 | 主要参数 |
|------|--------|---------------|
| `list_sheets` | 列出标签页 | spreadsheetId |
| `read_range` | 读取范围值（A1 表示法） | spreadsheetId, range |
| `write_range` | 将 2D 值写入范围 | spreadsheetId, range, values |
| `set_formula` | 将公式设置为单元格 | spreadsheetId, cell, formula |
| `add_sheet` | 添加新标签页 | spreadsheetId, title |
| `delete_sheet` | 删除标签页 | spreadsheetId, sheetTitle |
| `rename_sheet` | 重命名标签页 | spreadsheetId, oldTitle, newTitle |
| `freeze_rows` | 冻结顶部 N 行 | spreadsheetId, sheetTitle, rows |
| `set_format` | 设置背景 + 文字 + 粗体 | spreadsheetId, sheetTitle, startRow, endRow, startCol, endCol, bgHex, fontHex, bold |
| `set_column_width` | 设置列宽 | spreadsheetId, sheetTitle, startCol, endCol, width |
| `merge_cells` | 合并单元格 | spreadsheetId, sheetTitle, startRow, endRow, startCol, endCol |
| `set_borders` | 设置边框 | spreadsheetId, sheetTitle, startRow, endRow, startCol, endCol |
| `set_number_format` | 设置数字/日期格式 | spreadsheetId, sheetTitle, startRow, endRow, startCol, endCol, pattern |
| `set_data_validation` | 下拉验证 | spreadsheetId, sheetTitle, startRow, endRow, startCol, endCol, values |
| `set_conditional_format` | 条件格式 | spreadsheetId, sheetTitle, range, type, values, bgHex |
| `set_text_wrap_align` | 自动换行 + 对齐 | spreadsheetId, sheetTitle, startRow, endRow, startCol, endCol |
| `set_protected_range` | 保护范围 | spreadsheetId, sheetTitle, startRow, endRow, startCol, endCol |
| `apply_template` | 批量更新（一次多个请求） | spreadsheetId, requests |
### 技术说明
- Google Sheets 公式使用越南语环境，应使用 `;` 而不是 `,` - 例如：`=IF(A1>5;"达到";"未达到")`
- `spreadsheetId` 从 URL 获取：`https://docs.google.com/spreadsheets/d/{spreadsheetId}/edit`
- 要访问其他用户的 Sheet → 该用户必须与已授权的 Gmail 地址共享（查看者/编辑者）
- `set_format` 使用 0-based 网格范围（行/列从 0 开始）
### 常见错误处理
| 错误 | 原因 | 解决方法 |
|-----|-------------|----------|
| `没有 token.json` | 未运行授权 | `npm run auth` |
| `insufficient permission` | Sheet 未共享给 Gmail 地址 | 打开 Sheet → 分享 → 添加 Gmail 地址 |
| `找不到标签页 "..."` | 标签页名称错误 | 检查确切名称（带符号，空格） |
| `node: command not found` | 未安装 Node.js | 按照步骤 0 安装 Node.js |
| `git: command not found` | 未安装 Git | 按照步骤 1 安装 Git |
| `ECONNREFUSED` / `invalid_grant` | Token 过期 | 删除 `token.json`，重新运行 `npm run auth` |
