grist-mcp-server

gwhthompson/grist-mcp-server

3.2

If you are the rightful owner of grist-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

Grist MCP Server is a Model Context Protocol server designed to interface with the Grist API, providing a suite of tools for managing and interacting with Grist documents and data.

Tools
22
Resources
0
Prompts
0

Grist MCP Server

CI codecov npm 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)

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

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 for version history.

Links