# Grist MCP Server

[![CI](https://github.com/gwhthompson/grist-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/gwhthompson/grist-mcp-server/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/gwhthompson/grist-mcp-server/graph/badge.svg)](https://codecov.io/gh/gwhthompson/grist-mcp-server)
[![npm](https://img.shields.io/npm/v/grist-mcp-server)](https://www.npmjs.com/package/grist-mcp-server)
[![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-1.0-purple.svg)](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)