grist-mcp-server

Grist MCP 服务

Grist 的 MCP 服务。提供 11 个工具，用于处理文档、记录、SQL 和页面。

快速开始

Claude Code（推荐）

claude mcp add grist --env GRIST_API_KEY=your_api_key --env GRIST_BASE_URL=https://docs.getgrist.com -- npx -y grist-mcp-server

Claude Desktop（MCPB bundle）

1. 从 Releases 下载 grist-mcp-server.mcpb
2. 在 Claude Desktop 中：设置 → 开发者 → MCP Servers → 从 MCPB 安装
3. 配置 Grist API 密钥和基础 URL
4. 重启 Claude Desktop

手动配置（.mcp.json）

添加到你的 .mcp.json 文件中：

{
  "mcpServers": {
    "grist": {
      "command": "npx",
      "args": ["-y", "grist-mcp-server"],
      "env": {
        "GRIST_API_KEY": "your_api_key",
        "GRIST_BASE_URL": "https://docs.getgrist.com"
      }
    }
  }
}

从源代码安装

git clone https://github.com/gwhthompson/grist-mcp-server.git
cd grist-mcp-server
npm install && npm run build

添加到你的 MCP 配置中：

{
  "mcpServers": {
    "grist": {
      "command": "node",
      "args": ["/path/to/grist-mcp-server/dist/index.js"],
      "env": {
        "GRIST_API_KEY": "your_api_key",
        "GRIST_BASE_URL": "https://docs.getgrist.com"
      }
    }
  }
}

Cloudflare Workers（HTTP 传输）

使用 Cloudflare Workers 部署为远程 MCP 服务，通过 HTTP 访问。

本地开发：

npm run worker:dev

部署到 Cloudflare：

npm run worker:deploy

配置：

Workers 部署使用基于请求头的身份验证：

• X-Grist-API-Key：你的 Grist API 密钥（必需）
• X-Grist-Base-URL：Grist 实例 URL（可选，默认为 https://docs.getgrist.com）

端点： https://your-worker.workers.dev/mcp

请求示例：

curl -X POST https://your-worker.workers.dev/mcp \
  -H "Content-Type: application/json" \
  -H "X-Grist-API-Key: your_api_key" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

说明：

• 无状态设计：每个请求都会创建一个全新的服务实例
• 为所有来源启用 CORS（由于身份验证使用请求头而非 Cookie，因此是安全的）
• 通过 wrangler secret put GRIST_API_KEY 配置环境变量

工具

工具	用途
grist_get_workspaces	列出并筛选工作区
grist_get_documents	按 ID、名称或工作区查找文档
grist_get_tables	获取表结构和架构
grist_query_sql	执行包含 JOIN 和聚合的 SQL 查询
grist_get_records	使用筛选条件获取记录
grist_manage_records	执行所有记录 CRUD 操作（添加／更新／删除／插入或更新）
grist_manage_schema	架构操作：表、列、汇总
grist_manage_pages	页面布局和管理
grist_create_document	创建新的 Grist 文档或复制现有文档
grist_manage_webhooks	创建和管理 Webhook，以接收实时事件通知
grist_help	查找工具并通过 JSON 架构获取详细文档

示例

创建数据库

1. grist_get_workspaces → find workspace
2. grist_create_document → create document
3. grist_manage_schema → create tables with columns

导入数据

1. grist_get_documents → find document
2. grist_get_tables → check structure
3. grist_manage_records → upsert data (adds new, updates existing)

查询数据

1. grist_get_tables → understand schema
2. grist_query_sql → run SQL with JOINs and aggregations

故障排除

服务无法启动： 检查配置中是否已设置 GRIST_API_KEY。

身份验证失败： 在 https://docs.getgrist.com/settings/keys 验证 API 密钥。

文档列表为空： 检查 GRIST_BASE_URL 是否与 Grist 实例匹配。

连接错误（可自托管）： 确认 URL 包含 https://，且服务器可以访问。

测试

npm test  # Docker required - container lifecycle is automatic

文档

工具说明简明扼要。使用 grist_help 查看详情：

• grist_help({tools: ["grist_manage_records"], only: ["examples"]})
• grist_help({tools: ["grist_query_sql"], only: ["errors"]})

版本历史请参阅 CHANGELOG.md。

链接

• Grist 文档
• Grist 社区
• MCP 协议
• 报告问题