io.github.gwhthompson/grist-mcp-server

Name: io.github.gwhthompson/grist-mcp-server
Rating: 0.1 (1 reviews)
Author: gwhthompson

平台与服务

by gwhthompson

提供 11 个工具，帮助 AI 高效管理 Grist 文档，适合自动化整理与协作处理。

1GitHub

什么是 io.github.gwhthompson/grist-mcp-server？

提供 11 个工具，帮助 AI 高效管理 Grist 文档，适合自动化整理与协作处理。

README

Grist MCP Server

MCP server for Grist. 11 tools for documents, records, SQL, and pages.

Quick Start

Claude Code (recommended)

bash

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)

Download grist-mcp-server.mcpb from Releases
In Claude Desktop: Settings → Developer → MCP Servers → Install from MCPB
Configure your Grist API key and base URL
Restart Claude Desktop

Manual configuration (.mcp.json)

Add to your .mcp.json file:

json

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

Install from source

bash

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

Add to your MCP config:

json

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

Deploy as a remote MCP server using Cloudflare Workers for HTTP-based access.

Local development:

bash

npm run worker:dev

Deploy to Cloudflare:

bash

npm run worker:deploy

Configuration:

The Workers deployment uses header-based authentication:

X-Grist-API-Key: Your Grist API key (required)
X-Grist-Base-URL: Grist instance URL (optional, defaults to https://docs.getgrist.com)

Endpoint: https://your-worker.workers.dev/mcp

Example request:

bash

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}'

Notes:

Stateless design: Each request creates a fresh server instance
CORS enabled for all origins (safe because auth uses headers, not cookies)
Configure environment variables via wrangler secret put GRIST_API_KEY

Tools

Tool	Purpose
`grist_get_workspaces`	List and filter workspaces
`grist_get_documents`	Find documents by ID, name, or workspace
`grist_get_tables`	Get table structure and schema
`grist_query_sql`	Run SQL queries with JOINs and aggregations
`grist_get_records`	Fetch records with filters
`grist_manage_records`	All record CRUD operations (add/update/delete/upsert)
`grist_manage_schema`	Schema operations: tables, columns, summaries
`grist_manage_pages`	Page layout and management
`grist_create_document`	Create new Grist documents or copy existing ones
`grist_manage_webhooks`	Create and manage webhooks for real-time event notifications
`grist_help`	Discover tools and get detailed documentation with JSON schemas

Examples

Create a database

code

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

Import data

code

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

Query data

code

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

Troubleshooting

Server won't start: Check GRIST_API_KEY is set in config.

Authentication fails: Verify API key at https://docs.getgrist.com/settings/keys.

Empty document list: Check GRIST_BASE_URL matches your Grist instance.

Connection errors (self-hosted): Verify URL includes https:// and server is reachable.

Testing

bash

npm test  # Docker required - container lifecycle is automatic

Documentation

Tool descriptions are concise. Use grist_help for details:

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

See CHANGELOG.md for version history.

常见问题