English Français العربية

io.github.gwhthompson/grist-mcp-server

Official registry Productivity

11 tools for managing Grist documents with AI

Source code Documentation

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

NPM package grist-mcp-server
Claude Code 
claude mcp add grist-mcp-server -e 'GRIST_API_KEY=<your grist_api_key>' -e 'GRIST_BASE_URL=https://docs.getgrist.com' -- npx -y grist-mcp-server@2.0.33
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "grist-mcp-server": {
            "command": "npx",
            "args": [
                "-y",
                "grist-mcp-server@2.0.33"
            ],
            "env": {
                "GRIST_API_KEY": "<your grist_api_key>",
                "GRIST_BASE_URL": "https://docs.getgrist.com"
            }
        }
    }
}

Environment variables

  • GRIST_API_KEY required secret Your Grist API key
  • GRIST_BASE_URL Base URL for Grist instance (default: https://docs.getgrist.com)

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. Grist MCP Server
  2. Quick Start
  3. Tools
  4. Examples
  5. Troubleshooting
  6. Testing
  7. Documentation
  8. Links

Grist MCP Server

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

Quick Start

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. Download grist-mcp-server.mcpb from Releases
  2. In Claude Desktop: Settings → Developer → MCP Servers → Install from MCPB
  3. Configure your Grist API key and base URL
  4. 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

ToolPurpose
grist_get_workspacesList and filter workspaces
grist_get_documentsFind documents by ID, name, or workspace
grist_get_tablesGet table structure and schema
grist_query_sqlRun SQL queries with JOINs and aggregations
grist_get_recordsFetch records with filters
grist_manage_recordsAll record CRUD operations (add/update/delete/upsert)
grist_manage_schemaSchema operations: tables, columns, summaries
grist_manage_pagesPage layout and management
grist_create_documentCreate new Grist documents or copy existing ones
grist_manage_webhooksCreate and manage webhooks for real-time event notifications
grist_helpDiscover 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.

Frequently asked questions

What is io.github.gwhthompson/grist-mcp-server?

11 tools for managing Grist documents with AI

How do I install io.github.gwhthompson/grist-mcp-server?

It runs on your machine. In Claude Code: claude mcp add grist-mcp-server -e 'GRIST_API_KEY=<your grist_api_key>' -e 'GRIST_BASE_URL=https://docs.getgrist.com' -- npx -y grist-mcp-server@2.0.33. For other clients, paste the JSON configuration from this page into their MCP settings.

Does io.github.gwhthompson/grist-mcp-server need an API key?

Yes. It expects GRIST_API_KEY, which you set in its configuration.

Is io.github.gwhthompson/grist-mcp-server open source?

Its code is public on GitHub, but the repository does not declare a standard license.

Who maintains io.github.gwhthompson/grist-mcp-server?

It is published by gwhthompson. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.