# Grist MCP Server
[](https://github.com/gwhthompson/grist-mcp-server/actions/workflows/ci.yml)
[](https://codecov.io/gh/gwhthompson/grist-mcp-server)
[](https://www.npmjs.com/package/grist-mcp-server)
[](LICENSE)
[](https://modelcontextprotocol.io)
MCP server for Grist. 11 tools for documents, records, SQL, and pages.
## Quick Start
### Claude Code (recommended)
```bash
claude mcp add grist --env GRIST_API_KEY=your_api_key --env GRIST_BASE_URL=https://docs.getgrist.com -- npx -y grist-mcp-server
```
### Claude Desktop (MCPB bundle)
1. Download `grist-mcp-server.mcpb` from [Releases](https://github.com/gwhthompson/grist-mcp-server/releases)
2. In Claude Desktop: Settings → Developer → MCP Servers → Install from MCPB
3. Configure your Grist API key and base URL
4. Restart Claude Desktop
### Manual configuration (.mcp.json)
Add to your `.mcp.json` file:
```json
{
"mcpServers": {
"grist": {
"command": "npx",
"args": ["-y", "grist-mcp-server"],
"env": {
"GRIST_API_KEY": "your_api_key",
"GRIST_BASE_URL": "https://docs.getgrist.com"
}
}
}
}
```
### Install from source
```bash
git clone https://github.com/gwhthompson/grist-mcp-server.git
cd grist-mcp-server
npm install && npm run build
```
Add to your MCP config:
```json
{
"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"
}
}
}
}
```
## Tools
<!-- TOOLS_TABLE_START -->
| Tool | Purpose |
|------|---------|
| `grist_get_workspaces` | List and filter workspaces |
| `grist_get_documents` | Find documents by ID, name, or workspace |
| `grist_get_tables` | Get table structure and schema |
| `grist_query_sql` | Run SQL queries with JOINs and aggregations |
| `grist_get_records` | Fetch records with filters |
| `grist_manage_records` | All record CRUD operations (add/update/delete/upsert) |
| `grist_manage_schema` | Schema operations: tables, columns, summaries |
| `grist_manage_pages` | Page layout and management |
| `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 |
<!-- TOOLS_TABLE_END -->
## Examples
### Create a database
```
1. grist_get_workspaces → find workspace
2. grist_create_document → create document
3. grist_manage_schema → create tables with columns
```
### Import data
```
1. grist_get_documents → find document
2. grist_get_tables → check structure
3. grist_manage_records → upsert data (adds new, updates existing)
```
### Query data
```
1. grist_get_tables → understand schema
2. grist_query_sql → run SQL with JOINs and aggregations
```
## Troubleshooting
**Server won't start:** Check `GRIST_API_KEY` is set in config.
**Authentication fails:** Verify API key at https://docs.getgrist.com/settings/keys.
**Empty document list:** Check `GRIST_BASE_URL` matches your Grist instance.
**Connection errors (self-hosted):** Verify URL includes `https://` and server is reachable.
## Testing
```bash
npm test # Docker required - container lifecycle is automatic
```
## Documentation
Tool descriptions are concise. Use `grist_help` for details:
- `grist_help({tools: ["grist_manage_records"], only: ["examples"]})`
- `grist_help({tools: ["grist_query_sql"], only: ["errors"]})`
See [CHANGELOG.md](CHANGELOG.md) for version history.
## Links
- [Grist Documentation](https://support.getgrist.com)
- [Grist Community](https://community.getgrist.com)
- [MCP Protocol](https://modelcontextprotocol.io)
- [Report Issues](https://github.com/gwhthompson/grist-mcp-server/issues)
