gsheetmcp — MCP server đọc Google Sheet công khai

MCP server generic để đọc dữ liệu từ Google Sheet public qua endpoint gviz — không cần API key, OAuth, hay service account.

Cách chạy

Mặc định dùng stdio (cho Claude Desktop / MCP Hub qua uvx):

uvx gsheetmcp

Hoặc chạy local (từ source):

cd sheet-mcp-server
uv run server.py

SSE mode

Set env MCP_TRANSPORT=sse để dùng HTTP SSE transport:

MCP_TRANSPORT=sse uv run server.py

Server expose SSE endpoint /sse + /messages trên 0.0.0.0:8000. Cấu hình qua env var:

Env	Default	Mô tả
MCP_TRANSPORT	stdio	stdio hoặc 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	URL đầy đủ của Google Sheet (có hoặc không gid)
filter_column	string	no	Tên cột cần lọc (yêu cầu filter_value)
filter_value	string	no	Giá trị để lọc (so khớp in, case-insensitive)

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

Case	Response
URL sai định dạng	{"error": "invalid_sheet_url"}
Sheet không public	{"error": "sheet_not_public"}
filter_column không tồn tại	trả full data + "warning": "filter_column_not_found"
Tab rỗng	{"items": [], "total_matched": 0}
Timeout / network lỗi	{"error": "fetch_failed", "detail": "..."}

Ví dụ thực tế

Sheet 1: FAQ (2 cột: 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: tồn kho sản phẩm (khác cấu trúc hoàn toàn)

Với sheet có cấu trúc khác, columns và items tự động đổi theo — không có tên cột nào bị "dính" từ sheet trước.

Test cases

1. Sheet public + filter hợp lệ → filtered: true, đúng subset
2. Sheet public, không filter → filtered: false, toàn bộ rows
3. filter_column sai → full data + warning: filter_column_not_found
4. Sheet private → error: sheet_not_public
5. URL sai → error: invalid_sheet_url
6. 2 sheet khác cấu trúc → columns/items tự động đổi, không dính

Cấu hình MCP client

stdio (khuyên dùng — mặc định)

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

Hoặc nếu đã clone repo local:

{
  "mcpServers": {
    "gsheetmcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/gsheetmcp", "server.py"]
    }
  }
}

SSE (remote server)

Khi server chạy ở chế độ SSE, client cấu hình URL endpoint:

{
  "mcpServers": {
    "gsheetmcp": {
      "transport": "sse",
      "url": "http://host:8000/sse"
    }
  }
}

Giới hạn

• gviz là internal endpoint của Google Sheets, không phải REST API chính thức — không có SLA.
• Chỉ đọc được sheet ở chế độ public (Anyone with the link can view).
• Mỗi lần gọi chỉ đọc được 1 tab theo gid.
• Không support ghi, xoá, hay chỉnh sửa dữ liệu.
• Dung lượng sheet lớn có thể bị timeout (mặc định 30s).