io.github.gwhthompson/grist-mcp-server
11 tools for managing Grist documents with AI
Open source Open in the app JSON README (API)
About
11 tools for managing Grist documents with AI
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- gwhthompson
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 2.0.33
- Stars
- 3
- Forks
- 1
- Last push
- 2026-01-30T15:16:11Z
- Repository state
- ativo
- Language
- TypeScript
- Added
- 2026-08-29 03:02:56
- Updated
- 2026-08-29 03:02:56
- Origin id
io.github.gwhthompson/grist-mcp-server
README
# 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"
}
}
}
}
```
### Cloudflare Workers (HTTP transport)
Deploy as a remote MCP server using Cloudflare Workers for HTTP-based access.
**Local development:**
```bash
npm run worker:dev
```
**Deploy to Cloudflare:**
```bash
npm run worker:deploy
```
**Configuration:**
The Workers deployment uses header-based authentication:
- `X-Grist-API-Key`: Your Grist API key (required)
- `X-Grist-Base-URL`: Grist instance URL (optional, defaults to `https://docs.getgrist.com`)
**Endpoint:** `https://your-worker.workers.dev/mcp`
**Example request:**
```bash
curl -X POST https://your-worker.workers.dev/mcp \
-H "Content-Type: application/json" \
-H "X-Grist-API-Key: your_api_key" \
-d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
```
**Notes:**
- Stateless design: Each request creates a fresh server instance
- CORS enabled for all origins (safe because auth uses headers, not cookies)
- Configure environment variables via `wrangler secret put GRIST_API_KEY`
## 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)