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

Related MCP server: perplexity-mcp-server

Outils exposés (~51 outils)

1. Navigation & découverte

2. Lecture de données

3. Écriture de données

4. Schéma — Tables

5. Schéma — Colonnes

6. Documents — Cycle de vie

7. Workspaces

8. Contrôle d'accès

9. Exports & téléchargements

10. Snapshots & historique

11. Webhooks

12. Pièces jointes

13. Actions bas-niveau

14. Admin & performance

15. Organisation & profil

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.