Grist MCP Server
MCP server for Grist. 11 tools for documents, records, SQL, and pages.
Quick Start
Claude Code (recommended)
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.mcpbfrom 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:
{
"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
git clone https://github.com/gwhthompson/grist-mcp-server.git
cd grist-mcp-server
npm install && npm run build
Add to your MCP config:
{
"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"
}
}
}
}
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
1. grist_get_workspaces → find workspace
2. grist_create_document → create document
3. grist_manage_schema → create tables with columns
Import data
1. grist_get_documents → find document
2. grist_get_tables → check structure
3. grist_manage_records → upsert data (adds new, updates existing)
Query data
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
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.