内容
# gsheets-mcp
[](https://gsheets-mcp.trombella.org/)
[](./LICENSE)
一个**本地MCP（模型上下文协议）服务器**，允许Claude通过Google Sheets API v4读取和写入您的Google Sheets。
它完全在您自己的机器上运行。您使用OAuth2（“已安装应用程序”/桌面流）与您自己的Google帐户进行身份验证，并且您的数据永远不会通过任何第三方服务器。
**在MIT许可下免费开源。** 没有遥测，没有第三方服务器。
🌐 **网站：** <https://gsheets-mcp.trombella.org/>
## 您将获得
| 工具 | 功能 |
|---|---|
| `list_spreadsheets` | 列出您的Google Sheets（可选按名称过滤）。 |
| `get_sheet_info` | 获取电子表格的元数据：标题、语言和选项卡（名称、ID、大小）。 |
| `read_range` | 从范围（例如`Foglio1!A1:D10`）读取值。 |
| `update_range` | 将值写入/覆盖范围。 |
| `append_rows` | 在表格末尾追加行。 |
大多数工具需要一个**电子表格ID** — 表格网址中的长字符串：
`https://docs.google.com/spreadsheets/d/`**`<这是ID>`**`/edit`。
您也可以使用`list_spreadsheets`发现ID，而不是手动复制。
---
## 先决条件
- **Node.js 18+** (`node --version`)。
- 一个Google帐户。
---
## 第 1 部分 — 设置 Google Cloud（一次性）
您需要一个OAuth“桌面应用程序”客户端，以便服务器可以请求您的许可来访问您的表格。
### 1. 创建一个 Google Cloud 项目
1. 前往 <https://console.cloud.google.com/>。
2. 顶部栏 → 项目下拉菜单 → **新建项目**。给它一个名称（例如 `gsheets-mcp`）并创建它。确保它已选中。
### 2. 启用 API
1. 前往 **API 和服务 → 库** (<https://console.cloud.google.com/apis/library>)。
2. 搜索 **Google Sheets API**，打开它，点击 **启用**。
3. 搜索 **Google Drive API**，打开它，点击 **启用**。
> Drive API 仅由 `list_spreadsheets` 用于通过 `drive.readonly` 范围枚举您的表格。它不用于修改、移动或删除文件。
### 3. 配置 OAuth 同意屏幕
1. 前往 **API 和服务 → OAuth 同意屏幕**。
2. **用户类型：外部** → **创建**。（内部仅在 Google Workspace 组织中可用。）
3. 填写必填字段：应用程序名称（例如 `gsheets-mcp`），您的电子邮件作为 **用户支持电子邮件** 和 **开发者联系人**。您可以留空其他字段。**保存并继续**。
4. **范围**：您可以跳过在此处添加范围（应用程序在登录时请求它们）。 **保存并继续**。
5. **测试用户**：点击 **添加用户** 并添加 **您的 Google 电子邮件**。这是必需的 - 在“测试”模式下，只有列出的测试用户可以授权应用程序。 **保存并继续**。
6. 将应用程序保留在 **测试** 模式下。这对于个人使用是可以的，并且对于您自己的测试用户帐户永远不会过期。（发布到“生产”将触发 Google 的应用程序验证，这是您在此处不需要的。）
### 4. 创建 OAuth 客户端凭证
1. 前往 **API 和服务 → 凭证**。
2. **创建凭证 → OAuth 客户端 ID**。
3. **应用程序类型：桌面应用程序**。命名它（例如 `gsheets-mcp desktop`）。 **创建**。
4. 在确认对话框中，点击 **下载 JSON**。此文件包含您的 `client_id` 和 `client_secret`。
### 5. 放置凭证文件
将下载的文件另存为 **`credentials.json`** 在配置目录中：
```bash
mkdir -p ~/.config/gsheets-mcp
mv ~/Downloads/client_secret_*.json ~/.config/gsheets-mcp/credentials.json
```
> 保留此文件私有 - 它被 git 忽略。您可以使用环境变量 `GSHEETS_MCP_CREDENTIALS` 重写其位置（请参见 `.env.example`）。
---
## 第 2 部分 — 安装和构建
从项目文件夹：
```bash
npm install
npm run build
```
---
## 第 3 部分 — 登录（一次性）
运行交互式登录。它会在 Google 的同意屏幕上打开您的浏览器；批准访问后，令牌将保存到 `~/.config/gsheets-mcp/token.json`（之后会自动刷新）。
```bash
npm run login
# 等效于：node dist/index.js login
```
由于应用程序处于 **测试** 模式，Google 会显示 **“Google 未验证此应用程序”** 警告。这是您自己的应用程序的预期行为 - 点击 **高级 → 转到 gsheets-mcp（不安全）** 并继续。然后授予两个请求的权限（如下所示）。
当您在终端中看到 `✅ 授权完成` 时，您就完成了。
> **请求的范围：**
> - `https://www.googleapis.com/auth/spreadsheets` — 读取/写入您的电子表格。
> - `https://www.googleapis.com/auth/drive.readonly` — 只读，仅由 `list_spreadsheets` 用于枚举您的表格。它无法修改或删除文件。
>
> 要在任何时候撤销访问权限，请访问 <https://myaccount.google.com/permissions>。
>
> **注意：** 如果您升级服务器并且请求的范围发生变化，您必须再次运行 `npm run login` — 以前的同意不涵盖新的范围。每个机器（每台计算机存储自己的令牌）也是如此。
---
## 第 4 部分 — 将服务器添加到 Claude Desktop
打开Claude Desktop的配置文件：
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
在 `mcpServers` 下添加一个 `gsheets` 条目，指向编译后的入口点。使用此项目中 `dist/index.js` 的**绝对路径**：
```json
{
"mcpServers": {
"gsheets": {
"command": "node",
"args": ["/绝对路径/到/google-sheets-mcp/dist/index.js"]
}
}
}
```
保存文件并 **完全退出并重新打开Claude Desktop**。您现在应该看到可用的 `gsheets` 工具。尝试询问Claude类似的问题：
> “列出我的 Google Sheets，然后从名为‘预算’的表格中读取 `A1:C5`。”
### 在 Claude Code 中使用它
```bash
claude mcp add gsheets -- node /绝对路径/到/google-sheets-mcp/dist/index.js
```
---
## 用例（询问Claude）
- **列出：** “列出我的 Google Sheets” / “查找名称包含‘预算’的电子表格。”
- **信息：** “电子表格 `<ID>` 有哪些选项卡？”（返回确切的选项卡名称以使用）。
- **读取：** “从电子表格 `<ID>` 读取范围 `Foglio1!A1:D10`。”
- **更新：** “将值 `[[\"名称\",\"分数\"],[\"Ada\",42]]` 放入电子表格 `<ID>` 的 `Foglio1!A1` 开始。”
- **追加：** “在电子表格 `<ID>` 的 `Foglio1` 中追加行 `[\"Grace\", 99]`。”
### ⚠️ 注意：选项卡名称是本地化的
范围使用 **选项卡（表格）名称**，例如 `Sheet1!A1:D10`。但默认选项卡名称取决于您的 Google 帐户语言：英语为 `Sheet1`，**意大利语为 `Foglio1`**，西班牙语为 `Hoja1`，法语为 `Feuille1`，等等。使用错误的名称会返回 `无法解析范围：…`。
如果您不确定实际的选项卡名称，请打开表格并阅读底部的选项卡标签，或只需询问Claude读取整个表格，传递 **仅选项卡名称** 作为范围（例如 `Foglio1`）。一个用于列出确切选项卡名称的专用 `get_sheet_info` 工具正在开发中。
## 配置参考
所有配置项均为可选；默认配置可以直接使用。请参见 `.env.example`。
| 变量 | 默认值 | 用途 |
|---|---|---|
| `GSHEETS_MCP_CONFIG_DIR` | `~/.config/gsheets-mcp` | `credentials.json` / `token.json` 存储位置。 |
| `GSHEETS_MCP_CREDENTIALS` | `<config dir>/credentials.json` | OAuth 客户端文件路径。 |
| `GSHEETS_MCP_TOKEN` | `<config dir>/token.json` | 已保存令牌路径。 |
---
## 故障排除
- **“未认证。运行一次性登录。”** — 您尚未登录，或令牌文件丢失。运行 `npm run login`。
- **“未找到 OAuth 客户端凭证。”** — `credentials.json` 不在服务器期望的位置。检查第 1 部分，步骤 5。
- **浏览器中 `403 access_denied` ** — 您的 Google 帐户未列为测试用户。在 OAuth 同意屏幕 → 测试用户（第 1 部分，步骤 3.5）中添加它。
- **“请求权限不足。”** — 您保存的令牌早于范围更改（例如，`list_spreadsheets` 需要 `drive.readonly`）。重新运行 `npm run login` 以重新同意。
- **“无法解析范围：…”** — 选项卡名称错误。选项卡名称是本地化的（意大利语为 `Foglio1`，英语为 `Sheet1`）。使用 `get_sheet_info` 查看确切名称。
- **无 `refresh_token` 警告** — 在 <https://myaccount.google.com/permissions> 撤销应用程序权限，然后重新运行 `npm run login`。
- **Claude Desktop 中未显示工具** — 确认 `claude_desktop_config.json` 中的路径是绝对的，并且指向 `dist/index.js`，您已运行 `npm run build`，并且您已完全重新启动 Claude Desktop。
---
## 开发
```bash
npm run build # 编译到 dist/
npm run watch # 重新编译
npm run typecheck # 类型检查不产生输出
```
源代码布局：`src/index.ts`（入口点），`src/auth.ts`（OAuth），`src/sheetsClient.ts` 和 `src/driveClient.ts`（API 包装器），`src/tools/*`（每个 MCP 工具一个文件）。
---
## 许可证
在 [MIT 许可证](./LICENSE) 下发布。您可以自由使用、修改和分发它。如果它能为您节省时间，您可以用一杯咖啡支持开发 — 请参见 [网站](https://gsheets-mcp.trombella.org/) 获取链接。 ☕
> 不隶属于或得到 Google 的认可。“Google Sheets” 是 Google LLC 的商标。
