Seatable Mcp

SeaTable MCP

由 SeaTable GmbH 构建并维护的 SeaTable 官方模型上下文协议（MCP）服务。它让 AI Agent 可以通过一组专用工具与您工作区中的数据交互，包括读取、写入、搜索、关联和查询行。该服务有意专注于数据操作，而不涉及架构管理（创建/删除表或列），以精简工具集，确保自主 Agent 使用时的安全性。

快速开始

最快的入门方式取决于您的设置：

• SeaTable Cloud — 使用托管的 MCP 服务 mcp.seatable.com，无需安装
• 自托管 SeaTable — 在 IDE 中通过 npx 本地运行 MCP 服务

SeaTable Cloud（托管的 MCP 服务）

如果您使用 SeaTable Cloud，可以直接使用现成的托管 MCP 服务，无需安装。使用 Streamable HTTP 端点配置您的 MCP 客户端：

Claude Desktop — 添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "seatable": {
      "type": "streamable-http",
      "url": "https://mcp.seatable.com/mcp",
      "headers": {
        "Authorization": "Bearer your-api-token"
      }
    }
  }
}

Cursor / VSCode — 添加到您的 MCP 设置（JSON）中：

{
  "mcp.servers": {
    "seatable": {
      "type": "streamable-http",
      "url": "https://mcp.seatable.com/mcp",
      "headers": {
        "Authorization": "Bearer your-api-token"
      }
    }
  }
}

ChatGPT 和其他兼容 OAuth 的客户端 — 使用内置的 OAuth 流程。在 ChatGPT 的开发者模式中配置：

• 服务 URL： https://mcp.seatable.com/mcp
• 认证类型： OAuth
• 授权 URL： https://mcp.seatable.com/authorize
• 令牌 URL： https://mcp.seatable.com/token

在授权步骤中，系统会提示您输入 SeaTable API 令牌。

自托管 SeaTable

对于自托管的 SeaTable 实例，请通过 npx 在本地运行 MCP 服务。IDE 会自动启动并管理此进程。

Claude Desktop — 添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "seatable": {
      "command": "npx",
      "args": ["-y", "@seatable/mcp-seatable"],
      "env": {
        "SEATABLE_SERVER_URL": "https://your-seatable-server.com",
        "SEATABLE_API_TOKEN": "your-api-token"
      }
    }
  }
}

Cursor / VSCode — 添加到您的 MCP 设置（JSON）中：

{
  "mcp.servers": {
    "seatable": {
      "command": "npx",
      "args": ["-y", "@seatable/mcp-seatable"],
      "env": {
        "SEATABLE_SERVER_URL": "https://your-seatable-server.com",
        "SEATABLE_API_TOKEN": "your-api-token"
      }
    }
  }
}

部署选项

如果您需要运行自己的服务实例（例如，部署在自己的基础设施上、支持多个工作区，或以多租户模式运行），请使用以下选项之一。

HTTP 服务（网络访问）

使用 Streamable HTTP 传输运行本地 HTTP 服务：

PORT=3001 npx -y @seatable/mcp-seatable --sse

# Health check
curl http://localhost:3001/health

# MCP endpoint: POST/GET/DELETE http://localhost:3001/mcp

多工作区（自托管）

在单个进程中为多个工作区提供服务：

SEATABLE_SERVER_URL=https://your-seatable-server.com \
SEATABLE_BASES='[{"base_name":"CRM","api_token":"token_abc"},{"base_name":"Projects","api_token":"token_def"}]' \
npx -y @seatable/mcp-seatable

每个工具都会自动获得一个 base 参数。使用 list_bases 查看可用的工作区。

托管模式（多租户 HTTP）

用于托管 MCP 端点，让每个客户端使用自己的 SeaTable API 令牌进行身份验证：

SEATABLE_MODE=managed \
SEATABLE_SERVER_URL=https://your-seatable-server.com \
SEATABLE_TOKEN_SECRET=$(openssl rand -hex 32) \
PORT=3000 npx -y @seatable/mcp-seatable --sse

托管模式下必须设置 SEATABLE_TOKEN_SECRET。它会封装服务签发的 OAuth 令牌，因此无需将底层 SeaTable API 令牌交给客户端。请确保该值在服务重启后保持不变——更改该值会使所有已签发的访问令牌和刷新令牌失效，并要求所有客户端重新授权。

客户端通过 Authorization: Bearer <token> 传递凭据——不仅在会话初始化时需要，之后的每个请求也都需要，包括 GET 和 DELETE。mcp-session-id 标头仅用于路由；它本身永远不会被接受。每个请求都会重新验证，并且必须对应创建该会话的同一身份，否则服务会返回 401（凭据缺失或无效）或 403（凭据有效，但会话不匹配）。速率限制与之前相同（每个令牌每分钟 60 个请求、每个 IP 每分钟 120 个请求、每个令牌最多 20 个并发连接）。

OAuth 支持： 托管模式还提供 OAuth 2.0 端点（/authorize 和 /token），支持 ChatGPT 等兼容 OAuth 的客户端接入，无需外部 OAuth 提供方。用户会在授权流程中输入其 SeaTable API 令牌；服务会将其封装成自己的短时访问令牌（1 小时）和轮换刷新令牌（14 天）。原始 SeaTable API 令牌永远不会返回给客户端。

客户端必须先在 /register 注册：返回的 client_id 包含客户端名称及其 redirect_uris，服务只接受客户端已注册的回调（根据 RFC 8252，环回回调的端口可以不同）。必须使用 S256 PKCE，并且每个授权码都会绑定到客户端、确切的回调地址和挑战值。

授权码可以发送到哪里。 允许开放动态注册时，“已注册客户端”并不代表可信——任何人都可以注册。关键在于授权码是否会离开用户的设备：

回调	行为
环回地址（http://127.0.0.1:…、localhost、[::1]）	允许，无需额外步骤——授权码保留在用户的设备上
专用方案（cursor://、vscode://、com.example.app:/…）	允许，无需额外步骤——授权码交给本地应用
SEATABLE_OAUTH_TRUSTED_REDIRECT_HOSTS 中的主机上的 https	允许，无需额外步骤
任何其他主机上的 https	用户在单独页面确认目标地址后允许
远程明文 http、javascript:、data:、file:、blob:	拒绝

无法通过入口链接跳过确认：确认信息只会从表单正文读取，并且会通过 Sec-Fetch-Site 拒绝由外部页面自动提交的 POST。因此，受信任主机列表只是为了减少操作步骤——它不是一道门槛，不设置它也不会造成问题。

同意页面会首先显示授权将发送到的目标地址。应用名称会标注为自报，因为在开放注册的情况下，名称由注册客户端的人自行选择，无法验证。

OAuth 端点按 IP 限制速率（总体每分钟 30 次，令牌提交每分钟 10 次），因此不能将 /authorize 用作不受限制的 SeaTable API 令牌测试接口。

OAuth 端点遵循 MCP 规范（RFC 8414 元数据发现、PKCE、动态客户端注册）：

端点	路径
元数据发现	/.well-known/oauth-authorization-server
授权	/authorize
令牌	/token
客户端注册	/register

客户端 ID 和密钥不会经过验证——动态客户端注册会自动生成它们。

Docker

docker run -d --name seatable-mcp \
  -p 3000:3000 \
  -e SEATABLE_SERVER_URL=https://your-seatable-server.com \
  -e SEATABLE_API_TOKEN=your-api-token \
  seatable/seatable-mcp:latest

# Health check
curl http://localhost:3000/health

安全模型

不同传输模式的安全特性差异显著：

	stdio（默认）	自托管 HTTP	托管 HTTP
网络暴露	无（本地进程）	TCP 端口，无身份验证	TCP 端口，Bearer 身份验证
身份验证	无需（本地）	无	Bearer 令牌或 OAuth 2.0，向 SeaTable 验证
速率限制	无	无	按令牌、按 IP、全局
连接限制	不适用	无	每个令牌最多 20 个并发会话
数据范围	所有已配置的 Base	所有已配置的 Base	每个客户端令牌对应一个 Base

⚠️ 警告：自托管 HTTP 模式（--sse / --http）没有身份验证。任何能够访问该端口的人都可以完全访问所有已配置的 Base，包括写入和删除操作。仅在受信任的网络（localhost、Docker 内部网络）中运行，或将其置于负责身份验证的反向代理之后。对于不受信任的网络，请改用托管模式。

速率限制

SeaTable 自身的 API 网关会按 Base（默认：每个 base_uuid 每分钟 500 个请求）和按组织（每月配额）实施速率限制。无论请求来自 MCP 服务、Web 界面还是直接 API 调用，这些限制都适用。MCP 服务不会重复实施这些限制，而是在 SeaTable 返回 429 Too Many Requests 时自动采用指数退避策略重试。

在托管模式下，MCP 服务会添加自身的速率限制，以保护服务进程本身（而非 SeaTable 后端）：每个令牌每分钟 60 个请求、每个 IP 每分钟 120 个请求、新会话创建每分钟 30 次，以及每个令牌最多 20 个并发连接。

输入验证

所有工具输入都会在执行前使用 Zod 模式进行验证。写入工具（add_row、append_rows、update_rows、upsert_rows）还会根据表模式验证行数据：未知列会被拒绝，只读列（公式、自动编号、创建者等）会被剔除，并在响应中附注说明。

工具模式以 additionalProperties: true 发布，以保持与可能附加内部字段（例如 _meta）的 MCP 客户端兼容。服务端会忽略意外字段：这些字段不会导致错误，但也不会被处理。这是有意为之的权衡：更严格的验证可以改进对拼写错误的提示，但可能会破坏与 MCP 客户端的兼容性。

行响应

行响应包含所有列和 SeaTable 系统字段（_id、_mtime、_ctime、_creator、_last_modifier）。系统字段不会被过滤：更新和删除需要 _id，时间戳有助于排序和检查数据新鲜度，创建者和修改者字段则可通过 list_collaborators 解析为显示名称。

缓存

服务会将 Base 元数据（表和列定义）缓存 60 秒，以避免写入操作期间重复调用 API。读取模式的工具（get_schema、list_tables）始终绕过缓存并返回最新数据。如果缓存的模式已过期（例如某列已重命名），SeaTable API 会拒绝写入，AI Agent 可以调用 get_schema 刷新模式。

环境变量

必需：

• SEATABLE_SERVER_URL — SeaTable 服务 URL

身份验证（自托管模式下必须设置其中一项）：

• SEATABLE_API_TOKEN — 单个 Base 的 API 令牌
• SEATABLE_BASES — 多 Base：JSON 数组（例如，'[{"base_name":"CRM","api_token":"..."}]'）

可选：

• SEATABLE_MODE — selfhosted（默认）或 managed（支持多租户的 HTTP，每个客户端单独进行身份验证）
• SEATABLE_TOKEN_SECRET — managed 模式下必需，至少 32 个字符。用于密封签发的 OAuth 令牌和客户端注册信息；必须在重启后保持不变（openssl rand -hex 32）
• SEATABLE_ACCESS_TOKEN_TTL — 已签发访问令牌的有效期，单位为秒（默认值：3600，范围：30–2592000）。值越低，SeaTable 令牌被撤销后令牌仍可使用的时间窗口越短；值越高，如果客户端续期失败，用户就不必再次输入提示。刷新令牌的有效期绝不会短于访问令牌。
• SEATABLE_MOCK=true — 启用模拟模式以进行离线测试
• CORS_ALLOWED_ORIGINS — 允许的 CORS 来源列表，以逗号分隔（仅限 HTTP 模式；未设置时禁用）
• METRICS_PORT — Prometheus 指标端口（默认值：9090，仅限 HTTP 模式）

监控

在 HTTP 模式下，服务会在单独的端口（默认 9090）上公开 Prometheus 指标：

curl http://localhost:9090/metrics

可用指标：

指标	类型	描述
mcp_tool_calls_total{tool, status}	计数器	按名称和结果（成功/错误）统计工具调用
mcp_tool_calls_by_tool_total{tool}	计数器	每个工具的调用总数（无论结果如何）
mcp_tool_duration_seconds{tool}	直方图	工具执行时间
mcp_http_requests_total{method, status}	计数器	按方法和状态码统计 HTTP 请求
mcp_rate_limit_exceeded_total{type}	计数器	速率限制拒绝次数（global/per_ip/per_token）
mcp_auth_validations_total{result}	计数器	身份验证次数（成功/失败/缓存命中）
mcp_active_sessions	仪表盘	当前活动的 HTTP 会话数
mcp_active_connections	仪表盘	当前活动的连接数
seatable_api_requests_total{operation, status}	计数器	按操作统计 SeaTable API 调用
seatable_api_duration_seconds{operation}	直方图	SeaTable API 延迟

此外，还通过 prom-client 提供标准的 Node.js 指标（内存、CPU、事件循环）。

指标服务仅在 HTTP 模式（而非 stdio）下启动，并绑定到 0.0.0.0；在 Docker 中，请仅在内部网络中暴露该端口。

MCP 工具

架构检查

• list_tables — 获取所有表及其元数据
• get_schema — 获取完整的数据库结构
• list_bases — 列出可用的 Base（仅限多 Base 模式）
• list_collaborators — 列出有权访问该 Base 的用户（用于协作者列）

读取数据

• list_rows — 分页列出行（使用 query_sql 进行筛选/排序）
• get_row — 按 ID 获取特定行
• find_rows — 使用 DSL 在客户端筛选
• search_rows — 通过 SQL WHERE 子句搜索
• query_sql — 使用参数化输入执行 SQL 查询

写入数据

• add_row — 添加单行新数据
• append_rows — 批量插入行
• update_rows — 批量更新行
• upsert_rows — 按键列插入或更新行
• delete_rows — 按 ID 删除行

文件

• upload_file — 将文件或图像上传到某一行（以 base64 编码）
• download_file — 从文件或图像列读取文件内容（文本文件和 PDF 以文本形式提供，二进制文件提供下载链接，最大 1 MB）

链接

• link_rows — 创建行之间的关联
• unlink_rows — 移除行之间的关联

实用工具

• get_row_activities — 获取行的变更历史（谁在何时更改了什么，以及新旧值）
• create_snapshot — 创建当前 Base 的快照（冷却时间为 10 分钟）
• add_select_options — 向单选或多选列添加新选项（跳过已有选项，不会重复添加）
• ping_seatable — 执行健康检查并监控延迟

支持的列类型

SeaTable Base 可以包含许多不同的列类型。下表列出了可通过 API 写入的类型及其值格式。

列类型	可写入	值格式
文本	是	"string"
长文本	是	"Markdown string"
数字（含百分比、货币）	是	123.45
复选框	是	true / false
日期	是	"YYYY-MM-DD" 或 "YYYY-MM-DD HH:mm"
时长	是	"h:mm" 或 "h:mm:ss"
单选	是	"option name"
多选	是	["option a", "option b"]
电子邮件	是	"[email protected]"
URL	是	"https://..."
评分	是	4（整数）
地理位置	是	{"lat": 52.52, "lng": 13.40}
协作者	是	["[email protected]"] — 使用 list_collaborators 获取用户 ID
链接	是	使用 link_rows / unlink_rows 工具
图片 / 文件	是	使用 upload_file 上传（base64），使用 download_file 读取内容
公式 / 链接公式	否	只读，由 SeaTable 计算
创建者 / 创建时间 / 修改时间	否	只读，自动设置
自动编号	否	只读，自动设置
按钮 / 数字签名	否	无法通过 API 访问

工具示例

// List all tables
{ "tool": "list_tables", "args": {} }

// Get rows with pagination
{ "tool": "list_rows", "args": { "table": "Tasks", "page_size": 10 } }

// Add rows
{ "tool": "append_rows", "args": { "table": "Tasks", "rows": [{ "Title": "New Task", "Status": "Todo" }] } }

// SQL query
{ "tool": "query_sql", "args": { "sql": "SELECT Status, COUNT(*) as count FROM Tasks GROUP BY Status" } }

编程使用

import { createMcpServer } from '@seatable/mcp-seatable'

const server = await createMcpServer({
  serverUrl: 'https://your-seatable-server.com',
  apiToken: 'your-api-token',
})

模拟模式

SEATABLE_MOCK=true npm run dev

用于演示和测试的内存表格与行，无需连接正在运行的 SeaTable 实例。

开发

前置要求

• Node.js >= 20

设置

git clone https://github.com/seatable/seatable-mcp
cd seatable-mcp
npm install
cp .env.example .env   # Configure your SeaTable settings
npm run dev             # Start in watch mode

脚本

• npm run dev — 以监视模式启动服务（tsx）
• npm run build — 编译 TypeScript
• npm run start — 运行编译后的服务
• npm test — 运行测试（vitest）
• npm run lint — 检查代码
• npm run typecheck — 执行 TypeScript 类型检查

测试工具

node scripts/mcp-call.cjs ping_seatable '{}'
node scripts/mcp-call.cjs list_tables '{}'
node scripts/mcp-call.cjs list_rows '{"table": "Tasks", "page_size": 5}'

故障排除

问题	解决方案
Invalid API token	检查 SEATABLE_API_TOKEN
Base not found	检查 API token 的权限
Connection timeout	检查 SEATABLE_SERVER_URL 和网络访问情况
Permission denied	确保 API token 拥有所需的 Base 权限
You don't have permission to perform this operation on this base.	API token 为只读，或已超出行数限制
Asset quota exceeded.	存储空间配额已用尽 — 删除文件或升级套餐
too many requests	SeaTable 已限制请求速率 — 系统会自动退避重试（3 次）

许可证

MIT