Grist MCP Server

MCP (Model Context Protocol) server that connects Claude Desktop to Grist spreadsheets. It dynamically discovers documents, tables, and columns, and lets you read, write, and query data using natural language.

Features

• list_documents -- browse all orgs, workspaces, and docs
• list_tables -- discover tables inside a document
• list_columns -- inspect column names, types, and labels
• get_records -- read rows with filters, sorting, and limits
• add_records -- insert new rows
• update_records -- modify existing rows
• delete_records -- remove rows by ID
• query_sql -- run SQL SELECT queries directly

Quick Start

1. Clone and install

git clone <repo-url>
cd grist-mcp-server
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

2. Configure environment

Copy the example file and fill in your credentials:

cp .env.example .env

Variable	Required	Description
GRIST_API_KEY	Yes	API key from your Grist profile
GRIST_BASE_URL	Yes	Base URL of your Grist instance
GRIST_DOC_ID	No	Default document ID (saves typing)

3. Run locally (stdio transport)

python server.py

4. Run with HTTP transport (for Render)

MCP_TRANSPORT=streamable-http python server.py

Connect to Claude Desktop

Add the following to your claude_desktop_config.json:

Local (stdio)

{
  "mcpServers": {
    "grist": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"],
      "env": {
        "GRIST_API_KEY": "your_api_key",
        "GRIST_BASE_URL": "https://altitudedm.getgrist.com",
        "GRIST_DOC_ID": "9PRy5Jf5ayS3dDL9iYRHmU"
      }
    }
  }
}

Remote (Render deployment)

{
  "mcpServers": {
    "grist": {
      "url": "https://your-app.onrender.com/mcp"
    }
  }
}

Set environment variables on Render instead of in the config file.

Deploy on Render

1. Push this repo to GitHub.
2. Create a new Web Service on Render.
3. Connect the GitHub repo.
4. Render will auto-detect the render.yaml configuration.
5. Add GRIST_API_KEY in the Render dashboard environment variables.
6. Deploy.

The server will be available at https://your-app.onrender.com/mcp.

Usage Examples

Explore data

You: What documents do I have in Grist?
Claude: (calls list_documents) You have 3 documents: ...

You: Show me the tables in "Client Tracker"
Claude: (calls list_tables) The document has 4 tables: Clients, Projects, Invoices, Notes

You: What columns does the Clients table have?
Claude: (calls list_columns) Columns: name (Text), email (Text), status (Choice), ...

Read and filter

You: Show me the first 10 active clients
Claude: (calls get_records with filter={"status":["active"]}, limit=10)

You: How many invoices were created this month?
Claude: (calls query_sql with SQL: SELECT COUNT(*) FROM Invoices WHERE date >= '2025-01-01')

Write data

You: Add a new client: name=ACME Corp, status=active
Claude: (calls add_records) Created record with ID 42.

You: Mark client 42 as inactive
Claude: (calls update_records with id=42, fields={"status":"inactive"})

You: Delete client 99
Claude: (calls delete_records with record_ids=[99])

Running Tests

pip install pytest pytest-asyncio
pytest tests/ -v

Project Structure

grist-mcp-server/
├── server.py          # MCP server entry point (8 tools)
├── grist_client.py    # Async Grist API client
├── requirements.txt   # Python dependencies
├── render.yaml        # Render deployment config
├── .env.example       # Environment variable template
├── .gitignore
├── tests/
│   └── test_grist_client.py
└── README.md

License

MIT