内容
# Zoho 表格 MCP 服务器
适用于 [Zoho 表格](https://www.zoho.com/sheet/) 的零依赖 MCP（模型上下文协议）服务器，
以及一个 Claude 代码技能，教导代理如何有效地使用它。
与 Claude Code、Claude Desktop 和任何其他支持 stdio 的 MCP 客户端兼容。单个文件，无需 npm 安装，支持 Node 18+。
## 您将获得
| 工具 | 类型 | 功能描述 |
| --- | --- | --- |
| `sheet_list_workbooks` | 读取 | 列出包含 `resource_id` 的电子表格 |
| `sheet_list_worksheets` | 读取 | 列出工作簿中的选项卡 |
| `sheet_fetch_records` | 读取 | 以 JSON 记录形式获取行，支持条件筛选和分页 |
| `sheet_add_records` | 写入 | 追加行（键必须与表头行匹配） |
| `sheet_update_records` | 写入 | 更新匹配条件的行 |
| `sheet_delete_records` | 写入 | 根据条件或行 ID 删除或清除行 |
| `sheet_create_workbook` | 写入 | 创建新的空白工作簿 |
| `sheet_api_call` | 任意 | 用于 Data API v2 其他方法的逃生出口 |
写入工具在其描述中带有明确的“与用户确认”指令，因此表现良好的代理将向您引用确切的更改，然后再触及实时电子表格。
## 快速入门（Claude Code）
```bash
git clone https://github.com/NikkyAmresh/zoho-sheet-mcp.git
cd zoho-sheet-mcp
claude
```
然后输入 `/setup`。捆绑的设置命令引导 Claude 完成所有操作：
它询问您的数据中心和 Self Client 凭证，要求您粘贴授权码，
将授权码兑换为刷新令牌（写入 `.env`，chmod 600，永不回显），
通过 `workbook.list` 调用验证，注册服务器并通过 `claude mcp add -s user`，
并将用法技能安装到 `~/.claude/skills/`。当设置完成时重启会话，
`sheet_*` 工具即可使用。
如果您不使用 Claude Code，请按照下面的手动步骤进行。
## 手动设置
### 1. 创建 Zoho Self Client
1. 打开您数据中心的应用 API 控制台：`https://api-console.zoho.com/`
（或 `.in`、`.eu`、`.com.au`、`.jp`、`.ca`）。
2. 创建（或重用）一个 **Self Client**。记下 **Client ID** 和 **Client Secret**。
### 2. 配置环境
```bash
git clone https://github.com/NikkyAmresh/zoho-sheet-mcp.git
cd zoho-sheet-mcp
cp .env.example .env
chmod 600 .env
# 编辑 .env：设置 ZOHO_CLIENT_ID、ZOHO_CLIENT_SECRET、ZOHO_DC
```
`ZOHO_DC` 是您登录的 Zoho 域名的顶级域名：`com`、`in`、`eu`、
`com.au`、`jp` 或 `ca`。所有端点均由此派生。
### 3. 生成授权码并兑换
1. 在 API 控制台中，打开您的 Self Client，转到 **生成代码**，并使用
此范围（这两个是仅有的两个 Sheet 范围；创建、列出和删除都包含在内）：
```
ZohoSheet.dataAPI.READ,ZohoSheet.dataAPI.UPDATE
```
2. 将持续时间设置为 10 分钟，生成，复制代码，然后：
```bash
node scripts/exchange-token.mjs <grant_code>
```
脚本将 `ZOHO_REFRESH_TOKEN` 写入 `.env`（chmod 600）并仅打印
最后 4 个字符。刷新令牌不会过期；如有需要，请在 Zoho 账户的
连接应用页面中撤销。
### 4. 注册服务器
Claude Code：
```bash
claude mcp add -s user zoho-sheet -- node /absolute/path/to/zoho-sheet-mcp/server.mjs
```
或项目范围（项目根目录中的 `.mcp.json`）：
```json
{
"mcpServers": {
"zoho-sheet": {
"command": "node",
"args": ["/absolute/path/to/zoho-sheet-mcp/server.mjs"]
}
}
}
```
Claude Desktop（`claude_desktop_config.json`）：`mcpServers` 下的 `command`/`args` 格式相同。
### 5. 安装技能（可选，Claude Code）
该技能为代理提供最佳路径（列出工作簿、列出工作表，然后获取）、
条件语法和写入确认规则。
```bash
# 项目范围
mkdir -p .claude/skills && cp -r skills/zoho-sheet .claude/skills/
# 或用户范围
mkdir -p ~/.claude/skills && cp -r skills/zoho-sheet ~/.claude/skills/
```
## 烟雾测试
填写 `.env` 后：
```bash
( printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"sheet_list_workbooks","arguments":{"count":5}}}' \
; sleep 8 ) | node server.mjs
```
期望一个 `initialize` 回复，接着是一个 JSON 格式的工作簿列表。
## API 说明
- 基础 URL：`https://sheet.zoho.<dc>/api/v2`。每个调用都是一个表单编码的
POST 请求，带有 `method` 参数（`workbook.list`、`worksheet.records.fetch` 等）。
工作簿级别的操作访问 `/workbooks` 和 `/create`；其他操作访问 `/<resource_id>`。
- API 可以返回 HTTP 200 且 `status: "failure"` 在响应体中；服务器将
其视为错误并显示 `error_code`/`error_message`。
- 工作表名称区分大小写。首先列出它们；不要假设 `Sheet1`。
- 记录 API 将第一行始终视为表头行。
- 速率限制为每分钟每个操作，超过后有 5 分钟的限制；分页使用
`records_start_index`/`count` 而不是逐行循环。
## 安全
- `.env` 被 gitignore 且应保持 `chmod 600`。此存储库中的任何内容都不会
打印完整的令牌；交换脚本会掩盖其输出。
- 刷新令牌授予对 Zoho 账户可以访问的每个电子表格的读取和写入权限。
将其视为密码；通过 Zoho 的连接应用页面撤销并重新运行交换脚本来轮换。
## 许可证
MIT
