Grist Mcp Server

io.github.gwhthompsonPublished by GitHub account gwhthompsonv2.0.33Updated Oct 24, 2026

11 tools for managing Grist documents with AI

VerifiedSTDIODesktop onlyDatabases Productivity & Workflow Data & Analytics

Server details

Identifier: io.github.gwhthompson/grist-mcp-server
Transport: STDIO
Runtime: Desktop only
Trust: Verified
Published: Sep 16, 2026

Security note

MCP servers receive tool arguments from a conversation and may perform external actions. Review what a server can do before you enable it, and give it only the access it needs.

The registry verified the GitHub account gwhthompson for this listing. That does not show the account is the product's maker.

SourceWeft's checks cover whether the listing is complete and the endpoint answered; they do not review the server's code or what its tools do.

Add a badge to your README

Show readers this MCP server is listed on SourceWeft. The badge links to this page.

[![Listed on SourceWeft](https://sourceweft.com/badge/mcp/io.github.gwhthompson%2Fgrist-mcp-server.svg)](https://sourceweft.com/mcp/io.github.gwhthompson%2Fgrist-mcp-server?utm_source=readme&utm_medium=badge)

Overview

AI-generated overview

A local MCP server that lets an assistant browse, query and modify Grist documents, records, schemas and pages through 11 tools.

What you can do: List and find workspaces and documents, and create new documents or copy existing ones. Inspect table structure and run SQL queries with joins and aggregations. Fetch records with filters and perform record CRUD, including upsert. Manage schema (tables, columns, summaries) and page layouts. Create and manage webhooks for real-time event notifications. Look up tool documentation and JSON schemas through a built-in help tool.
When to use it: Useful when you keep structured data in Grist and want an assistant to explore it, answer questions with SQL, import or update records, or set up tables and pages without switching to the Grist interface.
Requirements: Runs as a local process via npx or Node.js from source; a Grist API key in GRIST_API_KEY is required, and GRIST_BASE_URL sets the instance (defaults to the hosted Grist service). Network access to the Grist instance is needed. An optional Cloudflare Workers deployment uses header-based authentication instead.

Before you install

The API key grants access to your Grist account's documents; keep it out of shared configs. Record, schema, page and webhook tools can add, update, delete and overwrite data, so changes should be reviewed before running. Webhooks send event notifications to endpoints you configure.

Installation

In SourceWeft

Open Grist Mcp Server in the dashboard and add it to a workspace.
Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

Grist MCP Server

[CI] [codecov] [npm] [License] [MCP]

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

{  "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.gitcd grist-mcp-servernpm install && npm run build

git clone https://github.com/gwhthompson/grist-mcp-server.gitcd grist-mcp-servernpm 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"      }    }  }}

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

Deploy to Cloudflare:

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

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 workspace2. grist_create_document → create document3. grist_manage_schema → create tables with columns

1. grist_get_workspaces → find workspace2. grist_create_document → create document3. grist_manage_schema → create tables with columns

Import data

1. grist_get_documents → find document2. grist_get_tables → check structure3. grist_manage_records → upsert data (adds new, updates existing)

1. grist_get_documents → find document2. grist_get_tables → check structure3. grist_manage_records → upsert data (adds new, updates existing)

Query data

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

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

Source: README.md at commit d75706c

Tools

SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

v2.0.33LatestSep 16, 2026

Score

40% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

Reached in the last 30 days25 pts
Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.
Auth declared10 pts
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
Tools listed15 pts
Answer tools/list without a credential, or ship a package that starts in a sandbox without one.
DescriptionRequired15 pts
Logo10 pts
Documentation15 pts
License10 pts
Declare a license in the repository or the registry entry.