mcp-server-grist

mcp-server-grist

3.4

If you are the rightful owner of mcp-server-grist and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

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

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/
├── docs/                  # Documentation et fichiers de rĂ©fĂ©rence
│   └── grist_api.yml      # Documentation de l'API Grist
├── archive/               # FonctionnalitĂ©s archivĂ©es
│   ├── christmas_order_tool.py     # Outil de commandes de NoĂ«l (dĂ©sactivĂ©)
│   ├── grist_form_tools.py         # IntĂ©gration des formulaires (dĂ©sactivĂ©)
│   └── grist_additional_tools.py    # Outils additionnels (dĂ©sactivĂ©)
├── grist_mcp_server.py    # Serveur MCP principal
├── requirements.txt       # DĂ©pendances Python
├── setup.py              # Configuration du package
├── Dockerfile            # Configuration Docker
├── .env.template         # Template pour les variables d'environnement
└── README.md             # Documentation

Prérequis

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

Installation

Via pip

pip install mcp-server-grist

Installation manuelle

git clone https://github.com/yourusername/mcp-server-grist.git
cd mcp-server-grist
pip install -r requirements.txt

Via Docker

docker build -t mcp/grist-mcp-server .

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

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"
      ]
    }
  }
}

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

Outils disponibles

Gestion des organisations et documents

  • list_organizations : Liste les organisations
  • list_workspaces : Liste les espaces de travail
  • list_documents : Liste les documents

Gestion des tables et colonnes

  • list_tables : Liste les tables
  • list_columns : Liste les colonnes
  • list_records : Liste les enregistrements avec tri et limite

Manipulation des données

  • add_grist_records : Ajoute des enregistrements
  • 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

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}]
)

Cas d'utilisation détaillés

Fonctions de base

  • list_organizations, list_workspaces, list_documents

    • Utilisez pour naviguer dans la structure de Grist
    • NĂ©cessaires pour obtenir les IDs des documents et tables
    • Pas de paramĂštres complexes
  • list_tables, list_columns

    • Utilisez pour explorer la structure d'un document
    • Utiles pour connaĂźtre les noms des colonnes avant de faire des requĂȘtes
    • Pas de paramĂštres de filtrage
  • list_records

    • Utilisez pour obtenir tous les enregistrements d'une table
    • Tri simple sur une seule colonne (ex: "name" ou "-age")
    • Limitation du nombre de rĂ©sultats
    • Ne supporte pas le filtrage (utilisez filter_sql_query Ă  la place)

Fonctions de filtrage SQL

  • filter_sql_query

    • Utilisez pour les filtres simples sur une seule table
    • Conditions WHERE basiques (Ă©galitĂ©, comparaison)
    • SĂ©lection de colonnes spĂ©cifiques
    • Tri et limitation des rĂ©sultats
    • Exemple : filtrer les employĂ©s actifs d'une organisation
  • execute_sql_query

    • Utilisez pour les requĂȘtes complexes
    • Jointures entre tables
    • Sous-requĂȘtes
    • AgrĂ©gations (GROUP BY, HAVING)
    • ParamĂštres SQL pour la sĂ©curitĂ©
    • Timeout personnalisable
    • Exemple : rapports complexes avec jointures

Fonctions de manipulation

  • add_grist_records

    • Utilisez pour crĂ©er de nouveaux enregistrements
    • Format simple : liste de dictionnaires
    • Pas besoin d'ID (gĂ©nĂ©rĂ©s automatiquement)
    • Exemple : ajouter de nouveaux clients
  • update_grist_records

    • Utilisez pour modifier des enregistrements existants
    • NĂ©cessite l'ID de chaque enregistrement
    • Mise Ă  jour partielle possible
    • Exemple : mettre Ă  jour les informations d'un client
  • delete_grist_records

    • Utilisez pour supprimer des enregistrements
    • NĂ©cessite la liste des IDs Ă  supprimer
    • OpĂ©ration irrĂ©versible
    • Exemple : supprimer des enregistrements obsolĂštes

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

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.