Grist MCP Server

What is this?

The Grist MCP Server is a specialized implementation of the Model-Connector-Processor protocol that lets AI agents and automation frameworks interact directly with your Grist documents. By exposing a secure, schema-aware API on top of Node.js and Express, it translates MCP calls into Grist REST operations so you can automate data entry, generate dynamic dashboards, or orchestrate complex workflows with ease.

With full CRUD access, schema introspection, and built-in support for OAuth2 or API keys, it ensures granular permissions and security. Whether you need to run batch updates, query table schemas, or register custom tools and prompts, the Grist MCP Server streamlines integration and makes Grist a first-class resource in any AI-driven pipeline.

Quick Start

Install the server using npm:

npm install @gristlabs/mcp-server

Then add it to your MCP client configuration:

{
  "mcpServers": {
    "grist-mcp-server": {
      "command": "npx",
      "args": ["-y", "@gristlabs/mcp-server"],
      "env": {
        "API_KEY": "your-api-key-here"
      }
    }
  }
}

Key Features

Feature 1: Full CRUD Access — create, read, update, and delete Grist documents, tables, and records programmatically.

Feature 2: Schema-Aware API — understands Grist table schemas, data types, and relationships to validate payloads and reduce integration errors.

Feature 3: Secure Permissions — supports OAuth2 and API key authentication, honoring Grist’s role-based access controls for granular security.

Example Usage

Here’s how you might query recent rows from a “Sales” table using the MCP client in JavaScript:

// Example code
const { McpClient } = require("mcp-js");
(async () => {
  const client = new McpClient({
    url: "http://localhost:5000",
    apiKey: process.env.MCP_API_KEY,
  });
  const resources = await client.listResources();
  const tableRes = resources.find(r => r.name === "Sales");
  const result = await client.callTool({
    name: "queryRows",
    arguments: {
      resourceId: tableRes.id,
      params: { filter: "Date >= '2023-01-01'", limit: 10 },
    }
  });
  console.log("Recent sales rows:", result.data);
})();

This code connects to the Grist MCP Server, lists available resources, finds the “Sales” table, and retrieves up to 10 rows filtered by date.

Configuration

The server accepts the following environment variables:

API_KEY – your Grist API key used to authenticate requests.

SETTING_1 (optional) – GRIST_API_URL, the URL of your Grist instance (defaults to https://docs.getgrist.com).

Available Tools/Resources

queryRows: Fetch rows from a table using filter and pagination parameters.

createRow: Insert a new row into a specified table programmatically.

Who Should Use This?

This server is perfect for:

Use case 1: AI developers looking to integrate Grist with language models and automation agents.

Use case 2: Automation engineers building data workflows and pipelines with n8n, Node-RED, or custom scripts.

Use case 3: BI analysts and reporting teams who need dynamic dashboards and batch data operations.

Conclusion

The Grist MCP Server streamlines programmatic access to Grist, combining robust CRUD tools, schema awareness, and secure authentication. Get started today to automate your data workflows and connect Grist seamlessly to AI agents or other MCP clients.

Check out the GitHub repository for more information and to contribute.