Grist MCP Server

Un serveur MCP (Model Context Protocol) pour interagir avec l'API Grist. Ce serveur permet d'accéder et de manipuler les données Grist directement depuis des modèles de langage comme Claude.

Structure du projet

mcp-server-grist/
├── src/
│   └── mcp_server_grist/     # Package principal
│       ├── __init__.py       # Point d'entrée du package
│       ├── __main__.py       # Support pour exécution en module
│       ├── version.py        # Gestion de version
│       ├── main.py           # Point d'entrée principal
│       ├── server.py         # Configuration du serveur MCP
│       ├── client.py         # Client API Grist
│       ├── tools/            # Outils MCP organisés par catégorie
│       └── models.py         # Modèles de données Pydantic
├── tests/                    # Tests unitaires et d'intégration
├── docs/                     # Documentation détaillée
├── requirements.txt          # Dépendances Python
├── pyproject.toml           # Configuration moderne du package
├── Dockerfile               # Configuration Docker
├── docker-compose.yml       # Configuration multi-services
├── .env.template            # Template pour variables d'environnement
└── README.md                # Documentation principale

Prérequis

• Python 3.8+
• Une clé API Grist valide
• Les packages Python suivants : fastmcp, httpx, pydantic, python-dotenv

Installation

Via pip (recommandé)

pip install mcp-server-grist

Après l'installation, vous pouvez exécuter le serveur avec :

mcp-server-grist

Utilisation avec Claude Desktop

Pour utiliser ce serveur MCP avec Claude Desktop, ajoutez la configuration suivante à votre fichier mcp_servers.json :

{
  "mcpServers": {
    "grist-mcp": {
      "command": "node",
      "args": [
        "chemin/vers/npm-wrapper/bin/start.js"
      ],
      "env": {
        "GRIST_API_KEY": "votre_clé_api_grist",
        "GRIST_API_URL": "https://docs.getgrist.com/api"
      }
    }
  }
}

Remplacez chemin/vers/npm-wrapper/bin/start.js par le chemin absolu vers le script start.js du wrapper Node.js inclus dans ce package.

Installation en mode développement

Pour contribuer ou personnaliser le serveur :

# Cloner le repository
git clone https://github.com/modelcontextprotocol/mcp-server-grist.git
cd mcp-server-grist

# Installer en mode développement
pip install -e .

# Lancer les tests
python -m pytest tests

Via Docker

Pour un déploiement rapide avec Docker :

# Construire l'image
docker build -t mcp/grist-mcp-server .

# Exécuter le container
docker run -it --rm \
  -e GRIST_API_KEY=votre_clé_api \
  -e GRIST_API_HOST=https://docs.getgrist.com/api \
  mcp/grist-mcp-server

Via Docker Compose

Pour déployer plusieurs modes de transport en parallèle :

# Configurer les variables d'environnement
cp .env.example .env
# Éditer le fichier .env avec votre clé API

# Lancer les services
docker-compose up

Configuration

Variables d'environnement

Créez un fichier .env basé sur .env.template avec les variables suivantes :

GRIST_API_KEY=votre_clé_api
GRIST_API_HOST=https://docs.getgrist.com/api
LOG_LEVEL=INFO  # Options: DEBUG, INFO, WARNING, ERROR, CRITICAL

Vous trouverez votre clé API dans les paramètres de votre compte Grist.

Configuration avec Claude Desktop

Ajoutez ceci à votre claude_desktop_config.json :

Version Python

{
  "mcpServers": {
    "grist-mcp": {
      "command": "python",
      "args": [
        "-m", "grist_mcp_server"
      ]
    }
  }
}

Version Docker

{
  "mcpServers": {
    "grist-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "GRIST_API_KEY=votre_clé_api",
        "-e", "GRIST_API_HOST=https://docs.getgrist.com/api",
        "mcp/grist-mcp-server"
      ]
    }
  }
}

Options de démarrage

Le serveur prend en charge plusieurs modes de transport conformes au standard MCP :

En mode module (recommandé)

# Mode stdio (par défaut pour Claude)
python -m mcp_server_grist --transport stdio

# Mode HTTP streamable (pour intégration web)
python -m mcp_server_grist --transport streamable-http --host 127.0.0.1 --port 8000 --path /mcp

# Mode Server-Sent Events (déprécié selon MCP 2025-03-26)
python -m mcp_server_grist --transport sse --host 127.0.0.1 --port 8000 --mount-path /sse

# Active le mode debug avec logging détaillé
python -m mcp_server_grist --debug

Options supplémentaires

Options:
  --transport {stdio,streamable-http,sse}
                        Type de transport à utiliser
  --host HOST           Hôte pour les transports HTTP (défaut: 127.0.0.1)
  --port PORT           Port pour les transports HTTP (défaut: 8000)
  --path PATH           Chemin pour streamable-http (défaut: /mcp)
  --mount-path MOUNT_PATH
                        Chemin pour SSE (défaut: /sse)
  --debug               Active le mode debug
  --help                Affiche l'aide

Sécurité des transports

Pour les transports HTTP et SSE, nous recommandons :

• Utiliser 127.0.0.1 (localhost) plutôt que 0.0.0.0 pour limiter l'accès au réseau local
• Activer la validation d'origine (validate_origin) pour éviter les attaques DNS rebinding
• Pour une exposition à Internet, utiliser un proxy inverse avec HTTPS

Fonctionnalités

• Accès aux données Grist directement depuis les modèles de langage
• Liste des organisations, espaces de travail, documents, tables et colonnes
• Gestion des enregistrements (création, lecture, mise à jour, suppression)
• Filtrage et tri des données avec des capacités de requêtage avancées
• Support des requêtes SQL (SELECT uniquement)
• Authentification sécurisée via clé API
• Gestion des accès utilisateurs
• Export et téléchargement (SQLite, Excel, CSV)
• Gestion des pièces jointes
• Gestion des webhooks
• Validation intelligente des formules

Outils disponibles

Gestion des organisations et documents

• list_organizations : Liste les organisations
• describe_organization : Obtient des informations détaillées sur une organisation
• modify_organization : Modifie une organisation
• delete_organization : Supprime une organisation
• list_workspaces : Liste les espaces de travail dans une organisation
• describe_workspace : Obtient des informations détaillées sur un espace de travail
• create_workspace : Crée un nouvel espace de travail
• modify_workspace : Modifie un espace de travail
• delete_workspace : Supprime un espace de travail
• list_documents : Liste les documents dans un espace de travail
• describe_document : Obtient des informations détaillées sur un document
• create_document : Crée un nouveau document
• modify_document : Modifie un document
• delete_document : Supprime un document
• move_document : Déplace un document vers un autre espace de travail
• force_reload_document : Force le rechargement d'un document
• delete_document_history : Supprime l'historique d'un document

Gestion des tables et colonnes

• list_tables : Liste les tables dans un document
• create_table : Crée une nouvelle table
• modify_table : Modifie une table
• list_columns : Liste les colonnes dans une table
• create_column : Crée une nouvelle colonne
• create_column_with_feedback : Crée une colonne avec validation et retour détaillé
• modify_column : Modifie une colonne
• delete_column : Supprime une colonne
• create_column_with_formula_safe : Crée une colonne de formule avec validation
• get_formula_helpers : Obtient de l'aide pour construire des formules
• validate_formula : Valide une formule et suggère des corrections
• get_table_schema : Obtient le schéma d'une table

Manipulation des données

• list_records : Liste les enregistrements avec tri et limite
• add_grist_records : Ajoute des enregistrements
• add_grist_records_safe : Ajoute des enregistrements avec validation
• update_grist_records : Met à jour des enregistrements
• delete_grist_records : Supprime des enregistrements

Filtrage et requêtes SQL

• filter_sql_query : Requête SQL optimisée pour le filtrage simple
  • Interface simplifiée pour les filtres courants
  • Support du tri et de la limitation
  • Conditions WHERE basiques
• execute_sql_query : Requête SQL complexe
  • Requêtes SQL personnalisées
  • Support des JOIN et sous-requêtes
  • Paramètres et timeout configurables

Gestion des accès

• list_organization_access : Liste les utilisateurs ayant accès à une organisation
• modify_organization_access : Modifie l'accès d'un utilisateur à une organisation
• list_workspace_access : Liste les utilisateurs ayant accès à un espace de travail
• modify_workspace_access : Modifie l'accès d'un utilisateur à un espace de travail
• list_document_access : Liste les utilisateurs ayant accès à un document
• modify_document_access : Modifie l'accès d'un utilisateur à un document

Export et téléchargement

• download_document_sqlite : Télécharge un document au format SQLite
• download_document_excel : Télécharge un document au format Excel
• download_table_csv : Télécharge une table au format CSV

Gestion des pièces jointes

• list_attachments : Liste les pièces jointes dans un document
• get_attachment_info : Obtient des informations sur une pièce jointe
• download_attachment : Télécharge une pièce jointe
• upload_attachment : Téléverse une pièce jointe

Gestion des webhooks

• list_webhooks : Liste les webhooks d'un document
• create_webhook : Crée un webhook
• modify_webhook : Modifie un webhook
• delete_webhook : Supprime un webhook
• clear_webhook_queue : Vide la file d'attente des webhooks

Exemples d'utilisation

# Liste des organisations
orgs = await list_organizations()

# Liste des espaces de travail
workspaces = await list_workspaces(org_id=1)

# Liste des documents
docs = await list_documents(workspace_id=1)

# Liste des tables
tables = await list_tables(doc_id="abc123")

# Liste des colonnes
columns = await list_columns(doc_id="abc123", table_id="Table1")

# Liste des enregistrements avec tri et limite
records = await list_records(
    doc_id="abc123",
    table_id="Table1",
    sort="name",
    limit=10
)

# Filtrage simple avec filter_sql_query
filtered_records = await filter_sql_query(
    doc_id="abc123",
    table_id="Table1",
    columns=["name", "age", "status"],
    where_conditions={
        "organisation": "OPSIA",
        "status": "actif"
    },
    order_by="name",
    limit=10
)

# Requête SQL complexe avec execute_sql_query
sql_result = await execute_sql_query(
    doc_id="abc123",
    sql_query="""
        SELECT t1.name, t1.age, t2.department
        FROM Table1 t1
        JOIN Table2 t2 ON t1.id = t2.employee_id
        WHERE t1.status = ? AND t1.age > ?
        ORDER BY t1.name
        LIMIT ?
    """,
    parameters=["actif", 25, 10],
    timeout_ms=2000
)

# Ajout d'enregistrements
new_records = await add_grist_records(
    doc_id="abc123",
    table_id="Table1",
    records=[{"name": "John", "age": 30}]
)

# Mise à jour d'enregistrements
updated_records = await update_grist_records(
    doc_id="abc123",
    table_id="Table1",
    records=[{"id": 1, "name": "John", "age": 31}]
)

# Création d'une colonne de formule avec validation
formula_column = await create_column_with_formula_safe(
    doc_id="abc123",
    table_id="Table1",
    column_label="Total",
    formula="$Prix * $Quantité",
    column_type="Numeric"
)

# Téléchargement d'un document au format Excel
excel_doc = await download_document_excel(
    doc_id="abc123",
    header_format="label"
)

# Gestion des accès
await modify_document_access(
    doc_id="abc123",
    user_email="[email protected]",
    access_level="editors"
)

Cas d'utilisation détaillés

Navigation et exploration

• list_organizations, list_workspaces, list_documents, list_tables, list_columns
  • Utilisez pour explorer la structure Grist et découvrir les données disponibles
  • Nécessaires pour obtenir les IDs avant d'exécuter des opérations spécifiques
  • Idéal pour la phase initiale d'analyse des données

Requêtes et filtrage

• list_records : Pour obtenir tous les enregistrements d'une table
• filter_sql_query : Pour les filtres simples sur une seule table
• execute_sql_query : Pour les requêtes complexes avec jointures et sous-requêtes

Manipulation des données

• add_grist_records et add_grist_records_safe : Pour ajouter des données avec ou sans validation
• update_grist_records : Pour modifier des enregistrements existants
• delete_grist_records : Pour supprimer des enregistrements

Travail avec les formules

• get_formula_helpers : Pour obtenir la syntaxe correcte des références de colonnes
• validate_formula : Pour vérifier et corriger automatiquement les formules
• create_column_with_formula_safe : Pour créer des colonnes calculées sécurisées

Export et téléchargement

• download_document_sqlite, download_document_excel, download_table_csv : Pour exporter les données
• download_attachment : Pour récupérer les fichiers attachés

Gestion des accès

• list_*_access et modify_*_access : Pour administrer les permissions utilisateurs

Intégrations externes

• create_webhook, modify_webhook : Pour connecter Grist à d'autres services

Cas d'utilisation

Le serveur MCP Grist est conçu pour :

• Analyser et résumer les données Grist
• Créer, mettre à jour et supprimer des enregistrements programmatiquement
• Construire des rapports et des visualisations
• Répondre aux questions sur les données stockées
• Connecter Grist avec des modèles de langage pour des requêtes en langage naturel
• Automatiser les flux de travail impliquant des données Grist
• Intégrer Grist à d'autres systèmes via webhooks

Contribution

Les contributions sont les bienvenues ! Voici comment contribuer :

1. Forkez le projet
2. Créez une branche pour votre fonctionnalité
3. Committez vos changements
4. Poussez vers la branche
5. Ouvrez une Pull Request

Licence

Ce serveur MCP est sous licence MIT.