内容
# 公共谷歌表格MCP服务器
用于通过 **gviz** 端点读取公共谷歌表格数据 - 无需API密钥、OAuth或服务帐户。
## 运行
默认模式为 **stdio** （适用于Claude Desktop / MCP Hub，借助 `uvx`）：
```bash
uvx gsheetmcp
```
或本地运行（从源代码）：
```bash
cd sheet-mcp-server
uv run server.py
```
### SSE模式
设置环境变量 `MCP_TRANSPORT=sse` 以使用HTTP SSE传输：
```bash
MCP_TRANSPORT=sse uv run server.py
```
服务器在 `0.0.0.0:8000` 上公开SSE端点 `/sse` 和 `/messages`。可通过以下方式配置：
| 环境变量 | 默认值 | 描述 |
|---|---|---|
| `MCP_TRANSPORT` | `stdio` | `stdio` 或 `sse` |
| `MCP_HOST` | `0.0.0.0` | 主机（SSE模式） |
| `MCP_PORT` | `8000` | 端口（SSE模式） |
## 工具：`get_sheet_data`
### 输入
| 参数 | 类型 | 必需 | 描述 |
|---|---|---|---|
| `sheet_url` | 字符串 | 是 | 完整的谷歌表格URL（带或不带 `gid`） |
| `filter_column` | 字符串 | 否 | 用于筛选的列名（需要 `filter_value`） |
| `filter_value` | 字符串 | 否 | 筛选值（`in`匹配，大小写不敏感） |
### 输出
```json
{
"sheet_id": "1p67eA4NGs389n-fuqHOmULhE5sfgRtFAulCHR8xcfGE",
"tab_gid": "1253624571",
"total_matched": 15,
"filtered": true,
"columns": ["Mã căn", "Tầng", "Diện tích", "Giá"],
"items": [
{ "Mã căn": "A-1201", "Tầng": "12", "Diện tích": "85", "Giá": "2.5 tỷ" }
]
}
```
### 错误响应
| 情况 | 响应 |
|---|---|
| 无效URL格式 | `{"error": "invalid_sheet_url"}` |
| 表格不公开 | `{"error": "sheet_not_public"}` |
| `filter_column` 未找到 | 返回完整数据 + `"warning": "filter_column_not_found"` |
| 空标签页 | `{"items": [], "total_matched": 0}` |
| 超时/网络错误 | `{"error": "fetch_failed", "detail": "..."}` |
## 示例
### 表格1：FAQ（2列：标题，描述）
**URL：** `https://docs.google.com/spreadsheets/d/1zwblTR5DWzgOiVxsDYJJkP5Gcmi4OGiCtldI0nyxZGo/edit?gid=0`
**请求：**
```json
{
"sheet_url": "https://docs.google.com/spreadsheets/d/1zwblTR5DWzgOiVxsDYJJkP5Gcmi4OGiCtldI0nyxZGo/edit?gid=0",
"filter_column": "Title",
"filter_value": "UI"
}
```
**响应：**
```json
{
"sheet_id": "1zwblTR5DWzgOiVxsDYJJkP5Gcmi4OGiCtldI0nyxZGo",
"tab_gid": "0",
"total_matched": 3,
"filtered": true,
"columns": ["Title", "Description"],
"items": [
{
"Title": "What's the difference between UI Kits and libraries",
"Description": "UI Kits are copy-and-pastable components..."
}
]
}
```
### 表格2：库存（完全不同的结构）
具有不同的表格结构，`columns` 和 `items` 自动适应 - 没有列名在不同表格之间泄露。
### 测试用例
1. 公共表格 + 有效筛选 → `filtered: true`，正确子集
2. 公共表格，无筛选 → `filtered: false`，所有行
3. 错误的 `filter_column` → 完整数据 + `warning: filter_column_not_found`
4. 私有表格 → `error: sheet_not_public`
5. 无效URL → `error: invalid_sheet_url`
6. 两个具有不同结构的表格 → columns/items 独立适应
## MCP客户端配置
### stdio（推荐 - 默认）
```json
{
"mcpServers": {
"gsheetmcp": {
"command": "uvx",
"args": ["git+https://github.com/kientv/gsheetmcp.git"]
}
}
}
```
或使用本地克隆：
```json
{
"mcpServers": {
"gsheetmcp": {
"command": "uv",
"args": ["run", "--directory", "/path/to/gsheetmcp", "server.py"]
}
}
}
```
### SSE（远程服务器）
当服务器在SSE模式下运行时，使用端点URL配置客户端：
```json
{
"mcpServers": {
"gsheetmcp": {
"transport": "sse",
"url": "http://host:8000/sse"
}
}
}
```
## 限制
- gviz是谷歌表格的内部端点，**不是官方REST API** - 无SLA。
- 仅适用于 **公共** 表格（任何具有链接的人都可以查看）。
- 每次调用读取 **1个标签页**，由 `gid` 指定。
- 无写入、删除或数据修改支持。
- 大型表格可能会超时（默认30秒）。
