Grist MCP Server

Micro-service HTTP autonome qui expose des outils MCP permettant à un client comme Perplexity de lire et d'écrire dans des documents Grist en langage naturel.

Comment ça marche (important à comprendre)

Ce n'est pas ce micro-service qui "comprend" le français. Dans le protocole MCP :

1. L'utilisateur écrit dans Perplexity : "Ajoute une ligne avec Nom=Dupont, Montant=120 dans la table Depenses".
2. Le modèle de Perplexity (lui-même) lit la liste des outils exposés par ce serveur (leurs noms, descriptions, paramètres) et décide d'appeler add_records avec les bons arguments JSON (docId, tableId, records).
3. Ce micro-service reçoit cet appel JSON-RPC structuré, traduit en appel HTTP vers l'API REST de Grist, puis renvoie le résultat à Perplexity, qui le reformule en français.

Votre travail (déjà fait dans ce dépôt) consiste donc surtout à :

• exposer des outils avec des descriptions et schémas très clairs (c'est ce qui guide le modèle de Perplexity),
• traduire ces outils en appels à l'API Grist (/api/docs/{docId}/tables/{tableId}/records, etc.).

Outils exposés (~51 outils)

1. Navigation & découverte

Outil	Usage
list_orgs	Lister les sites Grist accessibles
list_workspaces	Lister les workspaces/documents d'une organisation
find_document	Retrouver un docId à partir du nom du document
describe_document	Métadonnées complètes d'un document
list_tables	Lister les tables d'un document
get_table_schema	Lister les colonnes d'une table

2. Lecture de données

Outil	Usage
get_table_records	Lire des lignes (avec filtre/tri/limite)
run_sql_query	SELECT SQL en lecture seule, pour des agrégations

3. Écriture de données

Outil	Usage
add_records	Ajouter une ou plusieurs lignes
update_records	Modifier des lignes existantes
upsert_records	Ajouter ou mettre à jour selon des critères-clé
delete_records	⚠️ Supprimer des lignes (irréversible)

4. Schéma — Tables

Outil	Usage
create_table	Créer une ou plusieurs tables
update_table_metadata	Modifier les métadonnées d'une table
delete_table	⚠️ Supprimer une table (irréversible)

5. Schéma — Colonnes

Outil	Usage
add_columns	Ajouter des colonnes
update_columns	Modifier des colonnes existantes
upsert_columns	Ajouter ou mettre à jour une colonne
delete_column	⚠️ Supprimer une colonne (irréversible)

6. Documents — Cycle de vie

Outil	Usage
create_document	Créer un document vide
rename_document	Renommer un document
copy_document	Copier un document (ou son gabarit)
fork_document	Créer un fork personnel
move_document	Déplacer vers un autre workspace
pin_document	Épingler/désépingler
trash_document	Corbeille (ou suppression permanente ⚠️)
restore_document	Restaurer depuis la corbeille
delete_document	⚠️ Supprimer définitivement

7. Workspaces

Outil	Usage
create_workspace	Créer un workspace
rename_workspace	Renommer un workspace
trash_workspace	Corbeille (ou suppression permanente ⚠️)
restore_workspace	Restaurer depuis la corbeille
delete_workspace	⚠️ Supprimer définitivement (et tous ses documents)

8. Contrôle d'accès

Outil	Usage
get_document_access	Lister les rôles utilisateurs sur un document
update_document_access	Inviter/retirer/changer un rôle sur un document
get_workspace_access	Lister les rôles utilisateurs sur un workspace
update_workspace_access	Inviter/retirer/changer un rôle sur un workspace

9. Exports & téléchargements

Outil	Usage
get_download_url	URL authentifiée : CSV, TSV, XLSX, SQLite, schéma

10. Snapshots & historique

Outil	Usage
list_snapshots	Lister les sauvegardes automatiques
restore_from_snapshot	⚠️ Restaurer un document à un snapshot
get_document_history	Historique des actions (états/hashes)
truncate_document_history	Réduire la taille de l'historique
compare_document_versions	Comparer deux versions ou deux documents

11. Webhooks

Outil	Usage
list_webhooks	Lister les webhooks configurés
create_webhook	Créer un webhook (add/update)
update_webhook	Modifier un webhook existant
delete_webhook	Supprimer un webhook
clear_webhook_queue	Vider la file d'attente non livrée

12. Pièces jointes

Outil	Usage
list_attachments	Lister les métadonnées des pièces jointes
get_attachment_info	Métadonnées + URL de téléchargement d'une pièce jointe
upload_attachments	Téléverser une ou plusieurs pièces jointes (base64 → multipart/form-data)

13. Actions bas-niveau

Outil	Usage
apply_user_actions	Appliquer des actions internes Grist (AddRecord, RenameColumn, RenameTable, etc.) — pour tout ce que les autres outils ne couvrent pas

14. Admin & performance

Outil	Usage
reload_document	Forcer le rechargement (redémarre le moteur de formules)
flush_document	Forcer l'écriture immédiate sur disque
manage_formula_timing	Démarrer/arrêter/consulter le chronomètre de performance des formules

15. Organisation & profil

Outil	Usage
get_org_usage	Statistiques d'utilisation d'une organisation (docs, pièces jointes)
get_current_user	Profil de l'utilisateur authentifié par la clé API

Pour la demande "Analyse les données de la table X du document Y", Perplexity enchaînera typiquement : find_document (si Y est un nom) → list_tables/get_table_schema → get_table_records (ou run_sql_query pour une agrégation), puis fera l'analyse lui-même à partir des données renvoyées.

Pour "Attache ce fichier à la ligne X" : upload_attachments (retourne un ou plusieurs IDs numériques) → update_records en assignant ces IDs à une colonne de type Attachments.

Installation

cp .env.example .env
# éditez .env : GRIST_API_KEY, GRIST_API_URL, MCP_SERVER_TOKEN
npm install
npm start

Le serveur écoute sur http://localhost:3939/mcp.

Récupérer une clé API Grist

Compte Grist > Account settings > Developer > API keys > Create. ⚠️ Cette clé a les mêmes droits que votre compte sur tous vos documents. Pour limiter le risque, créez idéalement un compte Grist dédié ("service account") qui n'a accès qu'aux documents que vous voulez exposer à Perplexity, et utilisez sa clé API ici.

Tester en local

Avant de brancher Perplexity, vous pouvez tester avec MCP Inspector :

npx @modelcontextprotocol/inspector
# puis dans l'UI : URL = http://localhost:3939/mcp, Transport = Streamable HTTP
# Header: Authorization: Bearer <votre MCP_SERVER_TOKEN>

Déploiement

Perplexity exige une URL publique en HTTPS. Quelques options simples :

• Test rapide : ngrok http 3939 puis utilisez l'URL https://xxxx.ngrok-free.app/mcp.
• Production légère : déployez sur Render, Railway, Fly.io ou un petit VPS (avec Nginx/Caddy en reverse proxy pour le TLS). Le service est sans état persistant côté disque (tout passe par l'API Grist), donc une seule instance suffit largement, mais pensez à un stockage de session externe (Redis) si vous scalez à plusieurs instances, car transports est actuellement en mémoire.

Variables d'environnement à définir sur la plateforme de déploiement : GRIST_API_KEY, GRIST_API_URL, MCP_SERVER_TOKEN, PORT (souvent imposé par la plateforme).

Note pour upload_attachments : la taille maximale d'un fichier accepté dépend de la limite configurée sur votre document/site Grist ainsi que de la limite de payload de votre plateforme d'hébergement (souvent quelques Mo par défaut sur Render/Railway) — augmentez-la si vous prévoyez des pièces jointes volumineuses. L'encodage base64 augmente la taille du fichier d'environ 33% par rapport à l'original.

Connecter à Perplexity

Dans Perplexity : Account settings > Connectors > + Custom connector > Remote

• Name : Grist
• MCP Server URL : https://votre-domaine.tld/mcp
• Authentication : API Key → collez la valeur de MCP_SERVER_TOKEN
• Transport : Streamable HTTP
• Cochez la case de confirmation des risques, puis Add, puis activez le connecteur.

Activez ensuite le connecteur "Grist" sous Sources dans une conversation, et testez :

"Liste les tables du document Suivi Budget" "Analyse les données de la table Depenses du document Suivi Budget" "Ajoute une ligne dans la table Depenses avec Nom=Taxi, Montant=35, Date=2026-06-30" "Téléverse ce fichier et attache-le à la ligne 12 de la table Depenses"

Sécurité — pistes d'amélioration

• Remplacer la clé API Grist statique par une app OAuth Grist (voir la doc Grist sur les "Connected apps"), qui permet d'autoriser l'accès à des documents précis et de révoquer l'accès indépendamment du compte utilisateur — plus sûr qu'une clé API globale.
• Ajouter une journalisation des appels d'outils (qui a fait quoi, quand) si plusieurs personnes partagent ce connecteur.
• Restreindre ou retirer les outils destructifs si vous ne voulez pas que l'IA puisse supprimer des données ou de la structure : delete_records, delete_table, delete_column, delete_document, delete_workspace, restore_from_snapshot (remplace l'état courant), et apply_user_actions (accès bas-niveau très permissif).
• Limiter la taille et les types MIME acceptés par upload_attachments côté serveur si le connecteur est partagé, pour éviter les abus de stockage ou l'upload de fichiers non désirés.
• Envisager de retirer get_org_usage et get_current_user du périmètre exposé si le connecteur est partagé par plusieurs utilisateurs, ces outils exposant des informations de compte potentiellement sensibles.