Grist MCP Server

An MCP server implementation that provides tools for interacting with the Grist API, enabling integration between Grist spreadsheets and language models.

Features

Access Grist data directly from language models
List organizations, workspaces, documents, tables, and columns
Query, add, update, and delete records in Grist tables
Filter and sort data with rich query capabilities
Secure API key-based authentication

Tools

list_organizations

List all Grist organizations that the user has access to.

Returns: A list of organizations with their IDs, names, and domains.

list_workspaces

List all workspaces in a Grist organization.

Inputs:

org_id (int or string): The ID of the organization to list workspaces for

Returns: A list of workspaces with their IDs and names.

list_documents

List all documents in a Grist workspace.

Inputs:

workspace_id (int): The ID of the workspace to list documents for

Returns: A list of documents with their IDs and names.

list_tables

List all tables in a Grist document.

Inputs:

doc_id (string): The ID of the document to list tables for

Returns: A list of tables with their IDs.

list_columns

List all columns in a Grist table.

Inputs:

doc_id (string): The ID of the document containing the table
table_id (string): The ID of the table to list columns for

Returns: A list of columns with their IDs and field data.

list_records

List records in a Grist table with optional filtering, sorting, and limiting.

Inputs:

doc_id (string): The ID of the document containing the table
table_id (string): The ID of the table to list records from
filter_json (string, optional): JSON string for filtering records (e.g., '{"column_name": ["value1", "value2"]}')
sort (string, optional): Comma-separated list of columns to sort by (prefix with '-' for descending order)
limit (int, optional): Maximum number of records to return

Returns: A list of records with their IDs and field data.

add_grist_records

Add records to a Grist table.

Inputs:

doc_id (string): The ID of the document containing the table
table_id (string): The ID of the table to add records to
records (array): List of records to add as dictionaries of field values

Returns: A list of IDs for the newly created records.

update_grist_records

Update records in a Grist table.

Inputs:

doc_id (string): The ID of the document containing the table
table_id (string): The ID of the table to update records in
records (array): List of records to update (each must include "id" and field values)

Returns: A list of IDs for the updated records.

delete_grist_records

Delete records from a Grist table.

Inputs:

doc_id (string): The ID of the document containing the table
table_id (string): The ID of the table to delete records from
record_ids (array): List of record IDs to delete

Returns: A dictionary containing the operation status and a message.

Usage

The Grist MCP Server is designed for:

Analyzing and summarizing Grist data
Creating, updating, and deleting records programmatically
Building reports and visualizations based on Grist data
Answering questions about data stored in Grist tables
Connecting Grist with language models for natural language queries

Requirements

Python 3.8+
A valid Grist API key
The following Python packages: fastmcp, httpx, pydantic, python-dotenv

Setup

Environment Variables

Create a .env file with the following:

GRIST_API_KEY=your_api_key_here
GRIST_API_HOST=https://docs.getgrist.com/api

Replace your_api_key_here with your actual Grist API key, which you can find in your Grist account settings.

Configuration

Usage with Claude Desktop

Add this to your claude_desktop_config.json:

Direct Python

{
  "mcpServers": {
    "grist-mcp": {
      "command": "python",
      "args": [
        "-m", "grist_mcp_server"
      ]
    }
  }
}

Docker

{
  "mcpServers": {
    "grist-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "GRIST_API_KEY=your_api_key_here",
        "-e", "GRIST_API_HOST=https://docs.getgrist.com/api",
        "mcp/grist-mcp-server"
      ]
    }
  }
}

Building

Docker:

docker build -t mcp/grist-mcp-server .

Installation

pip install mcp-server-grist

Or manually:

git clone https://github.com/yourusername/mcp-server-grist.git
cd mcp-server-grist
pip install -r requirements.txt

License

This MCP server is licensed under the MIT License.