home / mcp / grist mcp server

Grist MCP Server

Provides MCP endpoints to manage Grist documents, workspaces, tables, records, and pages via a unified MCP interface.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "gwhthompson-grist-mcp-server": {
      "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"
      }
    }
  }
}

You can run the Grist MCP Server to expose Grist documents, workspaces, tables, and pages through a programmable MCP interface. It lets you list, query, and manipulate Grist data from an MCP client with a unified set of tools and endpoints.

How to use

You will interact with the Grist MCP Server through an MCP client. The server exposes a collection of tools that let you list workspaces, fetch documents, inspect schemas, run SQL queries, and perform CRUD operations on records and pages. Use the available tools to script common data workflows, build automations, or integrate Grist data into your own tools.

How to install

Prerequisites you need on your machine: Node.js and npm (or a compatible Node environment) to build and run the MCP server.

Option A: Quick start using 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

Install from source

If you prefer to install from source, clone the repository, install dependencies, and build the project. Then configure your MCP to run the built server.

git clone https://github.com/gwhthompson/grist-mcp-server.git
cd grist-mcp-server
npm install && npm run build

Manual configuration (.mcp.json)

Add a Grist entry to your MCP configuration to run the server via Node.js against the built dist entry.

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

Install from npm package (runtime path example)

If you want to run from the installed package in your environment, the final start command uses the built dist entry.

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

Available tools

grist_get_workspaces

List and filter workspaces to identify where documents reside and how they are organized.

grist_get_documents

Find documents by ID, name, or workspace to locate the target dataset.

grist_get_tables

Retrieve table structure and schema for understanding data layout.

grist_query_sql

Execute SQL queries with joins and aggregations across Grist data.

grist_get_records

Fetch records with filtering and pagination support.

grist_manage_records

Create, update, delete, or upsert records within a document.

grist_manage_schema

Manage tables, columns, and summaries to adjust schema.

grist_manage_pages

Control page layout and management within documents.

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.