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):

uvx gsheetmcp

Or run locally (from source):

cd sheet-mcp-server
uv run server.py

SSE mode

Set env MCP_TRANSPORT=sse for HTTP SSE transport:

MCP_TRANSPORT=sse uv run server.py

Server exposes SSE endpoint /sse + /messages on 0.0.0.0:8000. Configurable via:

Related MCP server: mcp-gsheet

Tool: get_sheet_data

Input

Output

{
  "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

Examples

Sheet 1: FAQ (2 columns: Title, Description)

URL: https://docs.google.com/spreadsheets/d/1zwblTR5DWzgOiVxsDYJJkP5Gcmi4OGiCtldI0nyxZGo/edit?gid=0

Request:

{
  "sheet_url": "https://docs.google.com/spreadsheets/d/1zwblTR5DWzgOiVxsDYJJkP5Gcmi4OGiCtldI0nyxZGo/edit?gid=0",
  "filter_column": "Title",
  "filter_value": "UI"
}

Response:

{
  "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)

{
  "mcpServers": {
    "gsheetmcp": {
      "command": "uvx",
      "args": ["git+https://github.com/kientv/gsheetmcp.git"]
    }
  }
}

Or with a local clone:

{
  "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:

{
  "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).