Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Grist MCP ServerShow me the first 10 active records from the Clients table"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.txt2. Configure environment
Copy the example file and fill in your credentials:
cp .env.example .envVariable | Required | Description |
| Yes | API key from your Grist profile |
| Yes | Base URL of your Grist instance |
| No | Default document ID (saves typing) |
3. Run locally (stdio transport)
python server.py4. Run with HTTP transport (for Render)
MCP_TRANSPORT=streamable-http python server.pyConnect 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
Push this repo to GitHub.
Create a new Web Service on Render.
Connect the GitHub repo.
Render will auto-detect the
render.yamlconfiguration.Add
GRIST_API_KEYin the Render dashboard environment variables.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/ -vProject 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.mdLicense
MIT
This server cannot be installed
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.