# Grist MCP Server

> Grist MCP Server is an open-source MCP server for databases. MCP server with 11 tools for Grist documents, records, SQL and page layouts. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, API, self-hosted
- **Repository:** https://github.com/gwhthompson/grist-mcp-server
- **MCP Registry name:** io.github.gwhthompson/grist-mcp-server
- **Categories:** [databases](https://ai-powered.com/categories/databases), [productivity](https://ai-powered.com/categories/productivity)
- **Listing updated:** 2026-11-18

## About

This community server connects an assistant to Grist, the spreadsheet-database tool, through the Grist API. Tools cover finding workspaces and documents, reading table schemas, fetching records with filters, running SQL with joins and aggregations, and managing records, schema, pages and webhooks. A grist_help tool returns documentation and JSON schemas for the others on demand.

One tool handles all record operations (add, update, delete and upsert), and another handles tables, columns and summaries, so a short chain such as find workspace, create document, create tables can build a small database from chat. It works with docs.getgrist.com or a self-hosted instance through GRIST_BASE_URL.

It runs locally over stdio from npm, as an MCPB bundle for Claude Desktop, from source, or as a stateless HTTP server on Cloudflare Workers that reads the API key from a request header. A Grist API key is required.

## Features

- **SQL queries:** Run SQL with joins and aggregations.
- **Record operations:** Add, update, delete and upsert in one tool.
- **Schema management:** Create tables, columns and summaries.
- **Webhooks:** Create and manage real-time event notifications.
- **Self-hosted support:** Point it at your own Grist instance.
- **Workers deployment:** Optional remote HTTP server on Cloudflare.

## Good for

- Build a small database from a chat
- Import data with upserts
- Query tables with SQL joins
- Adjust page layouts
- Set up webhooks on a document

## Install

### Claude Code (Terminal)

```sh
claude mcp add grist-mcp-server --env GRIST_API_KEY='<GRIST_API_KEY>' -- npx -y grist-mcp-server
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "grist-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "grist-mcp-server"
      ],
      "env": {
        "GRIST_API_KEY": "<GRIST_API_KEY>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "grist-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "grist-mcp-server"
      ],
      "env": {
        "GRIST_API_KEY": "<GRIST_API_KEY>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "grist-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "grist-mcp-server"
      ],
      "env": {
        "GRIST_API_KEY": "<GRIST_API_KEY>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "grist-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "grist-mcp-server"
      ],
      "env": {
        "GRIST_API_KEY": "<GRIST_API_KEY>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "grist-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "grist-mcp-server"
      ],
      "env": {
        "GRIST_API_KEY": "<GRIST_API_KEY>"
      }
    }
  }
}
```

## Tools

- `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`: Add, update, delete and upsert records.
- `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.
- `grist_help`: Discover tools and get documentation with JSON schemas.

## FAQ

### Which Grist can it use?

docs.getgrist.com by default, or a self-hosted instance via GRIST_BASE_URL.

### What is required?

A Grist API key.

### How is it installed?

Via npx, an MCPB bundle, from source, or on Cloudflare Workers.

### How many tools?

Eleven.

### Is Grist MCP Server free?

Yes. Grist MCP Server is open source, so you can use and self-host it for free.

### How do I add Grist MCP Server to Claude Code?

Run this command in your terminal: claude mcp add grist-mcp-server --env GRIST_API_KEY='<GRIST_API_KEY>' -- npx -y grist-mcp-server

### What are the best alternatives to Grist MCP Server?

The closest alternatives to Grist MCP Server are Ha MCP, Concord MCP, Midplane, note1 and Todoist.

## Where this comes from

- Description: written from the project's README.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [Ha MCP](https://ai-powered.com/mcp/ha-mcp): Ha MCP is an open-source MCP server for productivity.
- [Concord MCP](https://ai-powered.com/mcp/concord-mcp): Concord MCP is a freemium MCP server for developer tools.
- [Midplane](https://ai-powered.com/mcp/midplane): Midplane is an open-source MCP server for databases.
- [note1](https://ai-powered.com/mcp/note1): note1 is an MCP server for productivity.
- [Todoist](https://ai-powered.com/mcp/todoist): Todoist is a freemium MCP server for productivity.
- [Google_calendar](https://ai-powered.com/mcp/google-calendar-3): Google_calendar is a freemium MCP server for productivity.
- [Jira](https://ai-powered.com/mcp/jira): Jira is a freemium MCP server for productivity.
- [Google Workspace MCP Server](https://ai-powered.com/mcp/google-workspace-mcp-server-2): Google Workspace MCP Server is an open-source MCP server for productivity.

---
Source: https://ai-powered.com/mcp/grist-mcp-server
