Content
# gsheetmcp — Public Google Sheet MCP server
Generic MCP server for reading public Google Sheet data via the **gviz** endpoint — no API key, OAuth, or service account required.
## Running
Default mode is **stdio** (for Claude Desktop / MCP Hub via `uvx`):
```bash
uvx gsheetmcp
```
Or run locally (from source):
```bash
cd sheet-mcp-server
uv run server.py
```
### SSE mode
Set env `MCP_TRANSPORT=sse` for HTTP SSE transport:
```bash
MCP_TRANSPORT=sse uv run server.py
```
Server exposes SSE endpoint `/sse` + `/messages` on `0.0.0.0:8000`. Configurable via:
| Env | Default | Description |
|---|---|---|
| `MCP_TRANSPORT` | `stdio` | `stdio` or `sse` |
| `MCP_HOST` | `0.0.0.0` | Host (SSE mode) |
| `MCP_PORT` | `8000` | Port (SSE mode) |
## Tool: `get_sheet_data`
### Input
| Param | Type | Required | Description |
|---|---|---|---|
| `sheet_url` | `string` | yes | Full Google Sheet URL (with or without `gid`) |
| `filter_column` | `string` | no | Column name to filter on (requires `filter_value`) |
| `filter_value` | `string` | no | Filter value (`in` matching, case-insensitive) |
### Output
```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ỷ" }
]
}
```
### Error responses
| Case | Response |
|---|---|
| Invalid URL format | `{"error": "invalid_sheet_url"}` |
| Sheet not public | `{"error": "sheet_not_public"}` |
| `filter_column` not found | Returns full data + `"warning": "filter_column_not_found"` |
| Empty tab | `{"items": [], "total_matched": 0}` |
| Timeout / network error | `{"error": "fetch_failed", "detail": "..."}` |
## Examples
### Sheet 1: FAQ (2 columns: Title, Description)
**URL:** `https://docs.google.com/spreadsheets/d/1zwblTR5DWzgOiVxsDYJJkP5Gcmi4OGiCtldI0nyxZGo/edit?gid=0`
**Request:**
```json
{
"sheet_url": "https://docs.google.com/spreadsheets/d/1zwblTR5DWzgOiVxsDYJJkP5Gcmi4OGiCtldI0nyxZGo/edit?gid=0",
"filter_column": "Title",
"filter_value": "UI"
}
```
**Response:**
```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..."
}
]
}
```
### Sheet 2: Inventory (completely different structure)
With a different sheet structure, `columns` and `items` adapt automatically — no column names leak between sheets.
### Test cases
1. Public sheet + valid filter → `filtered: true`, correct subset
2. Public sheet, no filter → `filtered: false`, all rows
3. Bad `filter_column` → full data + `warning: filter_column_not_found`
4. Private sheet → `error: sheet_not_public`
5. Invalid URL → `error: invalid_sheet_url`
6. Two sheets with different structures → columns/items adapt independently
## MCP client config
### stdio (recommended — default)
```json
{
"mcpServers": {
"gsheetmcp": {
"command": "uvx",
"args": ["git+https://github.com/kientv/gsheetmcp.git"]
}
}
}
```
Or with a local clone:
```json
{
"mcpServers": {
"gsheetmcp": {
"command": "uv",
"args": ["run", "--directory", "/path/to/gsheetmcp", "server.py"]
}
}
}
```
### SSE (remote server)
When the server runs in SSE mode, configure the client with the endpoint URL:
```json
{
"mcpServers": {
"gsheetmcp": {
"transport": "sse",
"url": "http://host:8000/sse"
}
}
}
```
## Limitations
- gviz is an internal Google Sheets endpoint, **not an official REST API** — no SLA.
- Works only with **public** sheets (Anyone with the link can view).
- Each call reads **1 tab** specified by `gid`.
- No write, delete, or data modification support.
- Large sheets may timeout (default 30s).
