Grist MCP Server
This server lets an AI assistant browse, query, edit, and administer Grist documents through the Grist API — from reading records to creating whole schemas with relations.
Explore organizations, workspaces, documents, tables and columns, and inspect detailed table schemas
Read records with sorting/limits, or query data via simplified filtering (
filter_sql_query) or custom read-only SQL with joins and parameters (execute_sql_query)Write records: add (with optional validation), update, and delete records
Administer organizations, workspaces and documents (create, rename, move, delete, force reload, trim history)
Design schemas: create/rename tables, add/modify/delete columns (types, formulas, choices), build reference columns with two-way relations, and create a full schema with tables, relations and initial data in one call (plus
validate_schemaandexport_schemaas JSON/YAML/Mermaid)Manage access for organizations, workspaces and documents (list and modify user permissions)
Export documents/tables as SQLite, Excel or CSV
Handle attachments: list, inspect, download and upload files
Manage webhooks: list, create, modify, delete, and clear the queue
Allows exporting Grist documents into SQLite format and provides tools for executing SQL queries against the underlying database tables.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Grist MCP Server List all the tables in my Project Tracker document"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Grist MCP Server
An MCP (Model Context Protocol) server for the Grist API. It lets AI assistants such as Claude read and edit your Grist data: browse documents, query tables with SQL, add and update records, and create tables, columns and whole schemas with relations between tables.
Works with any Grist instance: docs.getgrist.com, self-hosted Grist, or grist.numerique.gouv.fr.
Quick start
You need Python 3.10+ and a Grist API key (Grist: Profile settings → API).
Add the server to your MCP client configuration. For Claude Desktop, edit claude_desktop_config.json:
{
"mcpServers": {
"grist": {
"command": "uvx",
"args": ["mcp-server-grist"],
"env": {
"GRIST_API_KEY": "your_grist_api_key",
"GRIST_API_URL": "https://docs.getgrist.com/api"
}
}
}
}uvx downloads and runs the package, no installation needed. Restart your client: the Grist tools are now available to the assistant.
Related MCP server: Moxie CRM MCP Server
Configuration
Variable | Required | Description |
| yes | Your Grist API key |
| no | API URL of your Grist instance, e.g. |
| no | Older name for the same setting, used when |
| no |
|
Variables can also be set in a .env file (see .env.template).
Other ways to run the server
With pip
pip install mcp-server-grist
mcp-server-grist # stdio, for local MCP clientsIn your MCP client, use "command": "mcp-server-grist" (or "command": "python", "args": ["-m", "mcp_server_grist"]) with the same env block as above.
Over HTTP
mcp-server-grist --transport streamable-http --host 127.0.0.1 --port 8000 --path /mcpOption | Default | Description |
|
|
|
|
| Interface for HTTP transports |
|
| Port for HTTP transports |
|
| Endpoint for |
|
| Endpoint for |
| Verbose logging |
Security: the server does not authenticate HTTP clients. Anyone who can reach it acts with your Grist API key. Keep the default 127.0.0.1, and put a reverse proxy with HTTPS and authentication in front of it before exposing it to a network.
With Docker
docker build -t mcp/grist-mcp-server .
# stdio
docker run -i --rm -e GRIST_API_KEY=your_key -e GRIST_API_URL=https://docs.getgrist.com/api \
mcp/grist-mcp-server
# HTTP (--host 0.0.0.0 is required inside a container)
docker run --rm -p 8000:8000 -e GRIST_API_KEY=your_key \
mcp/grist-mcp-server --transport streamable-http --host 0.0.0.0Without GRIST_API_URL, the image uses https://grist.numerique.gouv.fr/api. In an MCP client, use "command": "docker" with "args": ["run", "-i", "--rm", "-e", "GRIST_API_KEY=...", "mcp/grist-mcp-server"].
docker compose up starts a stdio and an HTTP service, configured from .env.
Available tools
The server exposes 54 tools. The tools reference lists the parameters of each one.
Navigation
list_organizations: list organizationsdescribe_organization: details of an organizationlist_workspaces: list the workspaces of an organizationdescribe_workspace: details of a workspacelist_documents: list the documents of a workspacedescribe_document: details of a documentlist_tables: list the tables of a documentlist_columns: list the columns of a tablelist_records: list records, with sorting and limitget_table_schema: detailed schema of a table
Records
add_grist_records: add recordsadd_grist_records_safe: add records after checking the column namesupdate_grist_records: update recordsdelete_grist_records: delete records
SQL queries
filter_sql_query: filter a table without writing SQL (conditions, sorting, limit)execute_sql_query: run a customSELECTquery (joins, subqueries, parameters, timeout)
Administration
modify_organization,delete_organization: manage an organizationcreate_workspace,modify_workspace,delete_workspace: manage workspacescreate_document,modify_document,delete_document: manage documentsmove_document: move a document to another workspaceforce_reload_document: reload a documentdelete_document_history: trim a document's historycreate_table,modify_table: create or rename a tablecreate_column,modify_column,delete_column: manage columns (types, formulas, choices, references)
Schemas and relations
create_schema: create tables, their columns, the relations between them and initial data in one callvalidate_schema: check a schema without creating anythingcreate_reference_column: create a reference column showing the chosen column of the target table, optionally with a two-way (reverse) relationexport_schema: export a document's schema as JSON, YAML or a Mermaid diagram
Access management
list_organization_access,modify_organization_access: users of an organizationlist_workspace_access,modify_workspace_access: users of a workspacelist_document_access,modify_document_access: users of a document
Export
download_document_sqlite: download a document as SQLitedownload_document_excel: download a table as Exceldownload_table_csv: download a table as CSV
Attachments
list_attachments: list the attachments of a documentget_attachment_info: metadata of an attachmentdownload_attachment: download an attachmentupload_attachment: upload an attachment
Webhooks
list_webhooks,create_webhook,modify_webhook,delete_webhook: manage webhooksclear_webhook_queue: empty the webhook queue
Examples
You normally just ask the assistant in plain language ("create a Projects table linked to Tasks"); it chooses the tools. The examples below show the corresponding tool calls and their arguments.
# Explore
await list_tables(doc_id="abc123")
await list_records(doc_id="abc123", table_id="Tasks", sort="-due_date", limit=10)
# Filter without SQL
await filter_sql_query(
doc_id="abc123",
table_id="Tasks",
columns=["title", "status"],
where_conditions={"status": "open"},
order_by="title",
limit=20
)
# Custom SQL (SELECT only)
await execute_sql_query(
doc_id="abc123",
sql_query="SELECT t.title, p.name FROM Tasks t JOIN Projects p ON t.project = p.id WHERE t.status = ?",
parameters=["open"]
)
# Add and update records
await add_grist_records(doc_id="abc123", table_id="Tasks",
records=[{"title": "Write docs", "status": "open"}])
await update_grist_records(doc_id="abc123", table_id="Tasks",
records=[{"id": 1, "status": "done"}])
# Formula column
await create_column(doc_id="abc123", table_id="Orders", column_id="total",
column_type="Numeric", label="Total", formula="$price * $quantity")
# Two related tables in one call
await create_schema(
doc_id="abc123",
schema={
"tables": {
"Projects": {"columns": {"name": {"type": "Text", "label": "Name"}}},
"Tasks": {"columns": {
"title": "Text",
"status": {"type": "Choice", "choices": ["open", "done"]},
"project": {"type": "Ref", "target": "Projects",
"visible": "name", "reverse": "tasks"}
}}
},
"data": {"Projects": [{"name": "Website"}]}
}
)
# Export a table to Excel
await download_document_excel(doc_id="abc123", table_id="Tasks", header="label")
# Share a document
await modify_document_access(doc_id="abc123", user_email="someone@example.com",
access_level="editors")In a schema, a reference column is written {"type": "Ref", "target": "Table", "visible": "column"} (or "Ref:Table"). "visible" is the column displayed in the cell; "reverse" adds the matching column in the target table, kept in sync by Grist. Re-running the same schema creates nothing twice: existing tables are left untouched.
Development
git clone https://github.com/nic01asFr/mcp-server-grist.git
cd mcp-server-grist
pip install -e ".[dev]"
pytest tests/The tools reference is generated from the code: after changing a tool, run python scripts/generate_tools_reference.py. See CONTRIBUTING.md for the contribution and release process, and the CHANGELOG for version history.
For AI agents
Machine-readable descriptions, generated from the code: llms.txt, SKILL.md (instructions for an agent), fiche-capacites.json and commandes.json (capability sheet in the Widgets Grist format).
Related projects
Project website: presentation and step-by-step setup (French and English)
Widgets Grist: widgets that turn a Grist document into a business application (map, planning, form, workload)
GristCoder: an MCP server to build widgets and pages directly in the document
Forum thread on the French-speaking Grist forum
Grist's official MCP server: available on getgrist.com (OAuth); this server works on any instance with an API key, including those where the official one is not enabled
License
MIT
Available Tools
54 toolsadd_grist_recordsAdd Grist RecordsC
Ajoute des enregistrements à une table Grist.
Inputs: doc_id (required), records (required), table_id (required). Returns: object
add_grist_records_safeAdd Grist Records SafeA
Ajoute des enregistrements avec validation préalable de la structure.
Cette version sécurisée valide l'existence de la table et des colonnes avant d'ajouter les enregistrements, et suggère des corrections si nécessaire.
Inputs: doc_id (required), records (required), table_id (required). Returns: object
clear_webhook_queueClear Webhook QueueB
Vide la file d'attente des webhooks pour un document.
Utile en cas d'accumulation de notifications non envoyées.
Inputs: doc_id (required). Returns: object
create_columnCreate ColumnC
Crée une nouvelle colonne dans une table.
Inputs: doc_id (required), table_id (required), column_id (required), label, +7 more. Returns: object
create_documentCreate DocumentC
Crée un nouveau document dans un espace de travail.
Inputs: name (required), workspace_id (required). Returns: object
create_reference_columnCreate Reference ColumnA
Crée une colonne de référence qui affiche la colonne choisie de la table cible.
Cette fonction:
Vérifie que les tables source et cible existent
Résout le nom (ID ou libellé) de la colonne visible
Crée la colonne de référence et règle son affichage
Optionnellement crée la relation inverse (référence à double sens Grist : les deux colonnes restent synchronisées)
Inputs: doc_id (required), table_id (required), column_id (required), target_table (required), +4 more. Returns: object
create_schemaCreate SchemaA
Crée un schéma complet avec tables, colonnes et relations.
Algorithme:
Validation du schéma (rien n'est créé si elle échoue)
Création des tables avec leurs colonnes simples
Création des colonnes de référence (colonne affichée réglée)
Création des relations inverses (références à double sens)
Insertion des données (optionnel)
Les tables déjà présentes dans le document ne sont jamais modifiées : ni colonnes, ni références, ni données ne leur sont ajoutées. Relancer le même schéma ne crée donc pas de doublons. Elles restent utilisables comme cibles de références.
Inputs: doc_id (required), schema (required), insert_data, skip_existing. Returns: object
create_tableCreate TableC
Crée une nouvelle table dans un document.
Inputs: doc_id (required), table_id (required), columns. Returns: object
create_webhookCreate WebhookC
Crée un webhook pour un document Grist.
Inputs: url (required), doc_id (required), memo, table_id, +1 more. Returns: object
create_workspaceCreate WorkspaceC
Crée un nouvel espace de travail dans une organisation.
Inputs: name (required), org_id (required). Returns: object
delete_columnDelete ColumnC
Supprime une colonne d'une table.
Inputs: doc_id (required), table_id (required), column_id (required). Returns: object
delete_documentDelete DocumentC
Supprime un document.
Inputs: doc_id (required). Returns: object
delete_document_historyDelete Document HistoryB
Supprime l'historique d'un document, ne conservant que les dernières actions.
Utile pour réduire la taille des documents volumineux.
Inputs: doc_id (required), keep. Returns: object
delete_grist_recordsDelete Grist RecordsC
Supprime des enregistrements d'une table Grist.
Inputs: doc_id (required), table_id (required), record_ids (required). Returns: object
delete_organizationDelete OrganizationC
Supprime une organisation.
Inputs: org_id (required). Returns: object
delete_webhookDelete WebhookC
Supprime un webhook.
Inputs: doc_id (required), webhook_id (required). Returns: object
delete_workspaceDelete WorkspaceC
Supprime un espace de travail.
Inputs: workspace_id (required). Returns: object
describe_documentDescribe DocumentC
Obtient des informations détaillées sur un document spécifique.
Inputs: doc_id (required). Returns: object
describe_organizationDescribe OrganizationC
Obtient des informations détaillées sur une organisation spécifique.
Inputs: org_id (required). Returns: object
describe_workspaceDescribe WorkspaceC
Obtient des informations détaillées sur un espace de travail spécifique.
Inputs: workspace_id (required). Returns: object
download_attachmentDownload AttachmentC
Télécharge le contenu d'une pièce jointe.
Inputs: doc_id (required), attachment_id (required). Returns: object
download_document_excelDownload Document ExcelC
Télécharge un document Grist au format Excel.
Inputs: doc_id (required), header, table_id. Returns: object
download_document_sqliteDownload Document SqliteB
Télécharge un document Grist au format SQLite.
Inputs: doc_id (required), template, nohistory. Returns: object
download_table_csvDownload Table CsvC
Télécharge une table Grist au format CSV.
Inputs: doc_id (required), table_id (required), header. Returns: object
execute_sql_queryExecute Sql QueryC
Exécute une requête SQL personnalisée sur un document Grist.
Permet d'exécuter des requêtes SQL complexes avec jointures, agrégations et sous-requêtes.
Inputs: doc_id (required), sql_query (required), parameters, timeout_ms. Returns: object
export_schemaExport SchemaC
Exporte le schéma d'un document existant.
Inputs: doc_id (required), format, include_data. Returns: object
filter_sql_queryFilter Sql QueryA
Exécute une requête SQL de filtrage sur une table Grist.
Version simplifiée pour requêtes SQL courantes sans écrire de SQL. Pour requêtes complexes, utiliser execute_sql_query.
Inputs: doc_id (required), table_id (required), limit, columns, +2 more. Returns: object
force_reload_documentForce Reload DocumentB
Force le rechargement d'un document.
Utile en cas d'incohérences ou de problèmes de synchronisation.
Inputs: doc_id (required). Returns: object
get_attachment_infoGet Attachment InfoC
Obtient les métadonnées d'une pièce jointe.
Inputs: doc_id (required), attachment_id (required). Returns: object
get_table_schemaGet Table SchemaB
Obtient le schéma détaillé d'une table Grist.
Inputs: doc_id (required), table_id (required). Returns: object
list_attachmentsList AttachmentsC
Liste les pièces jointes d'un document Grist.
Inputs: doc_id (required), sort, limit. Returns: object
list_columnsList ColumnsC
Liste toutes les colonnes dans une table Grist.
Inputs: doc_id (required), table_id (required). Returns: object
list_document_accessList Document AccessC
Liste les utilisateurs ayant accès à un document.
Inputs: doc_id (required). Returns: object
list_documentsList DocumentsC
Liste tous les documents dans un espace de travail Grist.
Inputs: workspace_id (required). Returns: object
list_organization_accessList Organization AccessC
Liste les utilisateurs ayant accès à une organisation.
Inputs: org_id (required). Returns: object
list_organizationsList OrganizationsB
Liste toutes les organisations Grist accessibles.
Inputs: no named parameters. Returns: object
list_recordsList RecordsC
Liste les enregistrements dans une table Grist avec tri et limitation optionnels.
Inputs: doc_id (required), table_id (required), sort, limit. Returns: object
list_tablesList TablesC
Liste toutes les tables dans un document Grist.
Inputs: doc_id (required). Returns: object
list_webhooksList WebhooksC
Liste les webhooks d'un document Grist.
Inputs: doc_id (required). Returns: object
list_workspace_accessList Workspace AccessC
Liste les utilisateurs ayant accès à un espace de travail.
Inputs: workspace_id (required). Returns: object
list_workspacesList WorkspacesC
Liste tous les espaces de travail dans une organisation Grist.
Inputs: org_id (required). Returns: object
modify_columnModify ColumnC
Modifie les propriétés d'une colonne.
Inputs: doc_id (required), table_id (required), column_id (required), label, +7 more. Returns: object
modify_documentModify DocumentC
Modifie les propriétés d'un document.
Inputs: doc_id (required), name, is_pinned. Returns: object
modify_document_accessModify Document AccessC
Modifie l'accès d'un utilisateur à un document.
Inputs: doc_id (required), user_email (required), access_level (required). Returns: object
modify_organizationModify OrganizationC
Modifie les propriétés d'une organisation.
Inputs: org_id (required), name. Returns: object
modify_organization_accessModify Organization AccessC
Modifie l'accès d'un utilisateur à une organisation.
Inputs: org_id (required), user_email (required), access_level (required). Returns: object
modify_tableModify TableC
Modifie les propriétés d'une table.
Inputs: doc_id (required), table_id (required), new_table_id. Returns: object
modify_webhookModify WebhookC
Modifie un webhook existant.
Inputs: doc_id (required), webhook_id (required), url, memo, +3 more. Returns: object
modify_workspaceModify WorkspaceC
Modifie les propriétés d'un espace de travail.
Inputs: workspace_id (required), name. Returns: object
modify_workspace_accessModify Workspace AccessC
Modifie l'accès d'un utilisateur à un espace de travail.
Inputs: user_email (required), access_level (required), workspace_id (required). Returns: object
move_documentMove DocumentC
Déplace un document vers un autre espace de travail.
Inputs: doc_id (required), target_workspace_id (required). Returns: object
update_grist_recordsUpdate Grist RecordsC
Met à jour des enregistrements existants dans une table Grist.
Inputs: doc_id (required), records (required), table_id (required). Returns: object
upload_attachmentUpload AttachmentC
Téléverse une pièce jointe dans un document Grist.
Inputs: doc_id (required), filename (required), content_base64 (required), content_type. Returns: object
validate_schemaValidate SchemaA
Valide un schéma sans le créer.
Vérifie:
Syntaxe du schéma
Existence des tables cibles pour les références
Existence des colonnes visibles ('visible') dans les tables cibles
Absence de conflit pour les colonnes inverses ('reverse')
Colonnes Choice/ChoiceList sans choix (avertissement)
Inputs: doc_id (required), schema (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 54 tools
Most tools target a distinct resource+action (create_workspace, list_documents, delete_column), so an agent can usually select correctly. A few pairs overlap: add_grist_records vs add_grist_records_safe do the same operation with different validation, and filter_sql_query vs execute_sql_query both run SQL (though descriptions distinguish simple vs complex cases).
The dominant pattern is consistent French verb_noun (create_/list_/describe_/modify_/delete_ + resource). Minor deviations exist: get_table_schema uses 'get' where others use 'describe', the 'grist' qualifier appears only on add/update/delete records, and downloads use verb_noun_noun (download_document_sqlite). These are readable and don't break predictability.
54 tools is very heavy for agent navigation, well past the 25+ 'too many' threshold. The breadth mirrors Grist's real API (orgs, workspaces, docs, tables, columns, records, access, downloads, attachments, webhooks, schemas), so few tools are truly redundant, but the surface is unwieldy and would benefit from consolidation.
Coverage is broad and near-complete CRUD across the hierarchy plus specialized areas (schema validation/creation, references, attachments, webhooks, access, exports). Minor gaps exist, e.g. no create_organization and no single-record get (only list_records), but these are edge operations an agent can work around.
Maintenance
Related MCP Connectors
Hosted MCP server for AI-driven data ops. Create apps, manage schemas, and CRUD structured data.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
ParseHub.dev is a hosted document-to-records service with a remote MCP server. Agents can upload a CSV, PDF, or Word file, summarize and analyze CSV data (filter, sort, group_by, and more), read text from PDF and Word files, extract attendees, agenda items, and action items from meeting notes, ask a question about an uploaded document, and store files as database records to list and read later. Each account sees only its own files and records. **Endpoint:** `https://parsehub.dev/mcp` (Streamable HTTP, stateless) **Auth:** API key in the `X-API-Key` header (keys start with `mcp_`), or `Authorization: Bearer <API key or JWT>`. Every request without credentials returns 401. **Plans:** Free (100 API requests/month, 1 document upload), or 5,000 requests/month on the $9/month or $42/year plan. Every MCP request counts toward the allowance. **Tools:** upload_csv, summarize_csv, analyze_csv, upload_document, read_document, extract_meeting_notes, ask_document, database_status, list_database_documents, get_database_document, store_document, extract_stored_meeting_notes, export_database (administrators only). Not affiliated with ParseHub (parsehub.com), the web-scraping tool. ParseHub.dev does not scrape websites. By Poietes LLC. Docs: https://parsehub.dev/guide#connect-via-mcp
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Related MCP Servers
- AlicenseAqualityCmaintenanceMCP server that allows interaction with PocketBase databases, enabling record operations (fetch, list, create, update), file management, and schema migrations through natural language.2243MIT
- AlicenseBqualityCmaintenanceAn MCP server that enables LLMs to interact with Moxie CRM. Provides comprehensive tools for managing clients, contacts, projects, invoices, time tracking, and more.309 npm3MIT
- FlicenseNot gradedqualityDmaintenanceMCP server that provides SQLite database operations. Allows AI assistants to query, modify and manage SQLite databases through the Model Context Protocol.-
- FlicenseNot gradedqualityDmaintenanceEnables reading and writing to Grist documents via natural language through MCP tools, allowing users to manage data, schemas, documents, and more using AI assistants like Perplexity.-