Skip to main content
Glama
Grist MCP Server
by nic01asFr

Grist MCP Server

PyPI version Python versions Tests License: MIT

Version française

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

GRIST_API_KEY

yes

Your Grist API key

GRIST_API_URL

no

API URL of your Grist instance, e.g. https://docs.getgrist.com/api (default) or https://grist.example.org/api

GRIST_API_HOST

no

Older name for the same setting, used when GRIST_API_URL is not set

LOG_LEVEL

no

DEBUG, INFO (default), WARNING, ERROR

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 clients

In 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 /mcp

Option

Default

Description

--transport

stdio

stdio, streamable-http, or sse (deprecated)

--host

127.0.0.1

Interface for HTTP transports

--port

8000

Port for HTTP transports

--path

/mcp

Endpoint for streamable-http

--mount-path

/sse

Endpoint for sse

--debug

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.0

Without 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 organizations

  • describe_organization: details of an organization

  • list_workspaces: list the workspaces of an organization

  • describe_workspace: details of a workspace

  • list_documents: list the documents of a workspace

  • describe_document: details of a document

  • list_tables: list the tables of a document

  • list_columns: list the columns of a table

  • list_records: list records, with sorting and limit

  • get_table_schema: detailed schema of a table

Records

  • add_grist_records: add records

  • add_grist_records_safe: add records after checking the column names

  • update_grist_records: update records

  • delete_grist_records: delete records

SQL queries

  • filter_sql_query: filter a table without writing SQL (conditions, sorting, limit)

  • execute_sql_query: run a custom SELECT query (joins, subqueries, parameters, timeout)

Administration

  • modify_organization, delete_organization: manage an organization

  • create_workspace, modify_workspace, delete_workspace: manage workspaces

  • create_document, modify_document, delete_document: manage documents

  • move_document: move a document to another workspace

  • force_reload_document: reload a document

  • delete_document_history: trim a document's history

  • create_table, modify_table: create or rename a table

  • create_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 call

  • validate_schema: check a schema without creating anything

  • create_reference_column: create a reference column showing the chosen column of the target table, optionally with a two-way (reverse) relation

  • export_schema: export a document's schema as JSON, YAML or a Mermaid diagram

Access management

  • list_organization_access, modify_organization_access: users of an organization

  • list_workspace_access, modify_workspace_access: users of a workspace

  • list_document_access, modify_document_access: users of a document

Export

  • download_document_sqlite: download a document as SQLite

  • download_document_excel: download a table as Excel

  • download_table_csv: download a table as CSV

Attachments

  • list_attachments: list the attachments of a document

  • get_attachment_info: metadata of an attachment

  • download_attachment: download an attachment

  • upload_attachment: upload an attachment

Webhooks

  • list_webhooks, create_webhook, modify_webhook, delete_webhook: manage webhooks

  • clear_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).

  • 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 tools
add_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:

  1. Vérifie que les tables source et cible existent

  2. Résout le nom (ID ou libellé) de la colonne visible

  3. Crée la colonne de référence et règle son affichage

  4. 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:

  1. Validation du schéma (rien n'est créé si elle échoue)

  2. Création des tables avec leurs colonnes simples

  3. Création des colonnes de référence (colonne affichée réglée)

  4. Création des relations inverses (références à double sens)

  5. 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

    C2.8/5.0

    Scored across 54 tools

    Disambiguation4/5

    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).

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    • Hosted MCP server for AI-driven data ops. Create apps, manage schemas, and CRUD structured data.

      https://www.chrysai.com/api/mcp
    • Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.

      https://mcp.niftypm.com/mcp
    • 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

      https://parsehub.dev/mcp
    • MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows

      https://mcp.flowra.dev/mcp

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      MCP server that allows interaction with PocketBase databases, enabling record operations (fetch, list, create, update), file management, and schema migrations through natural language.
      22
      43
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP server that provides SQLite database operations. Allows AI assistants to query, modify and manage SQLite databases through the Model Context Protocol.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      -