mcp-server-grist
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 organisationslist_workspaces
: Liste les espaces de travaillist_documents
: Liste les documents
Gestion des tables et colonnes
list_tables
: Liste les tableslist_columns
: Liste les colonneslist_records
: Liste les enregistrements avec tri et limite
Manipulation des données
add_grist_records
: Ajoute des enregistrementsupdate_grist_records
: Met Ă jour des enregistrementsdelete_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 :
- Forkez le projet
- Créez une branche pour votre fonctionnalité
- Committez vos changements
- Poussez vers la branche
- Ouvrez une Pull Request
Licence
Ce serveur MCP est sous licence MIT.