What can you do with this server?

The Grist MCP Server provides programmatic access to Grist (a spreadsheet-database hybrid) through 11 specialized tools: • Workspace & Document Management - Browse and filter workspaces, find documents by ID/name/workspace, create new documents, or fork existing ones • Data Querying - Fetch records with simple filters or execute complex SQL queries with JOINs and aggregations • Record Operations - Full CRUD capabilities (create, read, update, delete, upsert) with batched operations supporting cross-table dependencies • Schema Management - Create, rename, and delete tables and columns; add reference columns; create summary tables with automatic grouping • Page Layout - Manage page layouts with declarative column/row splits and link widgets together • Real-time Webhooks - Create and manage webhooks for event notifications on table changes • Built-in Documentation - Use grist_help tool to discover available tools and get detailed documentation with JSON schemas Deployment Options: Run locally via npx or from source, integrate with Claude Desktop/Code, or deploy as a Cloudflare Worker for HTTP-based access with header authentication.

How do I use Grist MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Grist MCP Server Show me the latest records from the Expenses table in my budget document" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Grist MCP Server

codecov npm License MCP

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.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:

{ "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" } } } }

Cloudflare Workers (HTTP transport)

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

Local development:

npm run worker:dev

Deploy to Cloudflare:

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:

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

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.

Links

This server cannot be installed

-

security - not tested

F

license - not found

-

quality - not tested

How are these scores calculated?

Resources

Need Help?

Report Issue

Related Servers

Tools

View all tools

Grist MCP Server

Grist MCP Server

Quick Start

Claude Code (recommended)

Claude Desktop (MCPB bundle)

Manual configuration (.mcp.json)

Install from source

Cloudflare Workers (HTTP transport)

Tools

Examples

Create a database

Import data

Query data

Troubleshooting

Testing

Documentation

Links

Resources

Tools

New MCP Servers

Latest Blog Posts

MCP directory API