{
  "markdown": "# Grist MCP Server\n\n[![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)\n[![codecov](https://codecov.io/gh/gwhthompson/grist-mcp-server/graph/badge.svg)](https://codecov.io/gh/gwhthompson/grist-mcp-server)\n[![npm](https://img.shields.io/npm/v/grist-mcp-server)](https://www.npmjs.com/package/grist-mcp-server)\n[![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE)\n[![MCP](https://img.shields.io/badge/MCP-1.0-purple.svg)](https://modelcontextprotocol.io)\n\nMCP server for Grist. 11 tools for documents, records, SQL, and pages.\n\n## Quick Start\n\n### Claude Code (recommended)\n\n```bash\nclaude mcp add grist --env GRIST_API_KEY=your_api_key --env GRIST_BASE_URL=https://docs.getgrist.com -- npx -y grist-mcp-server\n```\n\n### Claude Desktop (MCPB bundle)\n\n1. Download `grist-mcp-server.mcpb` from [Releases](https://github.com/gwhthompson/grist-mcp-server/releases)\n2. In Claude Desktop: Settings → Developer → MCP Servers → Install from MCPB\n3. Configure your Grist API key and base URL\n4. Restart Claude Desktop\n\n### Manual configuration (.mcp.json)\n\nAdd to your `.mcp.json` file:\n\n```json\n{\n  \"mcpServers\": {\n    \"grist\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"grist-mcp-server\"],\n      \"env\": {\n        \"GRIST_API_KEY\": \"your_api_key\",\n        \"GRIST_BASE_URL\": \"https://docs.getgrist.com\"\n      }\n    }\n  }\n}\n```\n\n### Install from source\n\n```bash\ngit clone https://github.com/gwhthompson/grist-mcp-server.git\ncd grist-mcp-server\nnpm install && npm run build\n```\n\nAdd to your MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"grist\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/grist-mcp-server/dist/index.js\"],\n      \"env\": {\n        \"GRIST_API_KEY\": \"your_api_key\",\n        \"GRIST_BASE_URL\": \"https://docs.getgrist.com\"\n      }\n    }\n  }\n}\n```\n\n### Cloudflare Workers (HTTP transport)\n\nDeploy as a remote MCP server using Cloudflare Workers for HTTP-based access.\n\n**Local development:**\n\n```bash\nnpm run worker:dev\n```\n\n**Deploy to Cloudflare:**\n\n```bash\nnpm run worker:deploy\n```\n\n**Configuration:**\n\nThe Workers deployment uses header-based authentication:\n\n- `X-Grist-API-Key`: Your Grist API key (required)\n- `X-Grist-Base-URL`: Grist instance URL (optional, defaults to `https://docs.getgrist.com`)\n\n**Endpoint:** `https://your-worker.workers.dev/mcp`\n\n**Example request:**\n\n```bash\ncurl -X POST https://your-worker.workers.dev/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-Grist-API-Key: your_api_key\" \\\n  -d '{\"jsonrpc\":\"2.0\",\"method\":\"tools/list\",\"id\":1}'\n```\n\n**Notes:**\n- Stateless design: Each request creates a fresh server instance\n- CORS enabled for all origins (safe because auth uses headers, not cookies)\n- Configure environment variables via `wrangler secret put GRIST_API_KEY`\n\n## Tools\n\n<!-- TOOLS_TABLE_START -->\n| Tool | Purpose |\n|------|---------|\n| `grist_get_workspaces` | List and filter workspaces |\n| `grist_get_documents` | Find documents by ID, name, or workspace |\n| `grist_get_tables` | Get table structure and schema |\n| `grist_query_sql` | Run SQL queries with JOINs and aggregations |\n| `grist_get_records` | Fetch records with filters |\n| `grist_manage_records` | All record CRUD operations (add/update/delete/upsert) |\n| `grist_manage_schema` | Schema operations: tables, columns, summaries |\n| `grist_manage_pages` | Page layout and management |\n| `grist_create_document` | Create new Grist documents or copy existing ones |\n| `grist_manage_webhooks` | Create and manage webhooks for real-time event notifications |\n| `grist_help` | Discover tools and get detailed documentation with JSON schemas |\n<!-- TOOLS_TABLE_END -->\n\n## Examples\n\n### Create a database\n\n```\n1. grist_get_workspaces → find workspace\n2. grist_create_document → create document\n3. grist_manage_schema → create tables with columns\n```\n\n### Import data\n\n```\n1. grist_get_documents → find document\n2. grist_get_tables → check structure\n3. grist_manage_records → upsert data (adds new, updates existing)\n```\n\n### Query data\n\n```\n1. grist_get_tables → understand schema\n2. grist_query_sql → run SQL with JOINs and aggregations\n```\n\n## Troubleshooting\n\n**Server won't start:** Check `GRIST_API_KEY` is set in config.\n\n**Authentication fails:** Verify API key at https://docs.getgrist.com/settings/keys.\n\n**Empty document list:** Check `GRIST_BASE_URL` matches your Grist instance.\n\n**Connection errors (self-hosted):** Verify URL includes `https://` and server is reachable.\n\n## Testing\n\n```bash\nnpm test  # Docker required - container lifecycle is automatic\n```\n\n## Documentation\n\nTool descriptions are concise. Use `grist_help` for details:\n\n- `grist_help({tools: [\"grist_manage_records\"], only: [\"examples\"]})`\n- `grist_help({tools: [\"grist_query_sql\"], only: [\"errors\"]})`\n\nSee [CHANGELOG.md](CHANGELOG.md) for version history.\n\n## Links\n\n- [Grist Documentation](https://support.getgrist.com)\n- [Grist Community](https://community.getgrist.com)\n- [MCP Protocol](https://modelcontextprotocol.io)\n- [Report Issues](https://github.com/gwhthompson/grist-mcp-server/issues)\n",
  "bytes": 5140,
  "sha": "5b4466d423b8cdf734e9dc4e0db56d549007ad52355226fc23eb4fd30bad651f",
  "repo_slug": "gwhthompson/grist-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_gwhthompson_grist_mcp_server_1ab8310f/readme"
}