Keboola MCP Server
officielCréez des workflows de données robustes, des intégrations et des analyses sur une plateforme intuitive unique.
Documentation
Serveur MCP Keboola
Connectez vos agents IA, clients MCP (Cursor, Claude, Windsurf, VS Code ...) et autres assistants IA à Keboola. Exposez les données, les transformations, les requêtes SQL et les déclencheurs de jobs, sans code supplémentaire. Fournissez les bonnes données aux agents quand et où ils en ont besoin.
Aperçu
Le serveur MCP Keboola est un pont open-source entre votre projet Keboola et les outils d'IA modernes. Il transforme les fonctionnalités de Keboola, comme l'accès au stockage, les transformations SQL et les déclencheurs de jobs, en outils appelables pour Claude, Cursor, CrewAI, LangChain, Amazon Q, et plus encore.
Fonctionnalités
Avec l'agent IA et le serveur MCP, vous pouvez :
- Stockage : Interroger directement les tables et gérer les descriptions des tables ou des buckets
- Composants : Créer, lister et inspecter les extracteurs, writers, applications de données et configurations de transformation
- SQL : Créer des transformations SQL en langage naturel
- Jobs : Exécuter des composants et des transformations, et récupérer les détails d'exécution des jobs
- Flux : Construire et gérer des pipelines de workflow à l'aide de flux conditionnels et de flux d'orchestration
- Applications de données : Créer, déployer et gérer des applications de données Keboola Streamlit affichant vos requêtes sur les données de stockage
- Métadonnées : Rechercher, lire et mettre à jour la documentation du projet et les métadonnées des objets en langage naturel
- Branches de développement : Travaillez en toute sécurité dans des branches de développement en dehors de la production, où toutes les opérations sont limitées à la branche sélectionnée
🚀 Démarrage rapide : Serveur MCP distant (Méthode la plus simple)
La façon la plus simple d'utiliser le serveur MCP Keboola est via notre serveur MCP distant. Cette solution hébergée élimine le besoin de configuration locale, de paramétrage ou d'installation.
Qu'est-ce que le serveur MCP distant ?
Notre serveur distant est hébergé sur chaque stack Keboola multi-tenant et prend en charge l'authentification OAuth. Vous pouvez vous y connecter depuis n'importe quel assistant IA prenant en charge la connexion HTTP Streamable distante et l'authentification OAuth.
Comment se connecter
- Obtenez l'URL de votre serveur distant : Accédez aux paramètres de votre projet Keboola → onglet
MCP Server - Copiez l'URL du serveur : Elle ressemblera à
https://mcp.<YOUR_REGION>.keboola.com/mcp - Configurez votre assistant IA : Collez l'URL dans les paramètres MCP de votre assistant IA
- Authentifiez-vous : Vous serez invité à vous authentifier avec votre compte Keboola et à sélectionner votre projet
Clients pris en charge
- Cursor : Utilisez le bouton "Installer dans Cursor" dans les paramètres du serveur MCP de votre projet ou cliquez sur ce bouton
- Claude Desktop : Ajoutez l'intégration via Paramètres → Intégrations
- Claude Code : Installez en utilisant
claude mcp add --transport http keboola <URL>(voir ci-dessous pour plus de détails) - Windsurf : Configurez avec l'URL du serveur distant
- Make : Configurez avec l'URL du serveur distant
- Autres clients MCP : Configurez avec l'URL du serveur distant
Configuration de Claude Code
Claude Code est un outil d'interface en ligne de commande qui vous permet d'interagir avec Claude en utilisant votre terminal. Vous pouvez installer l'intégration du serveur MCP Keboola à l'aide d'une simple commande.
Installation :
Exécutez la commande suivante dans votre terminal, en remplaçant <YOUR_REGION> par votre région Keboola :
claude mcp add --transport http keboola https://mcp.<YOUR_REGION>.keboola.com/mcp
Commandes spécifiques à la région :
| Région | Commande d'installation |
|---|---|
| US Virginia AWS | claude mcp add --transport http keboola https://mcp.keboola.com/mcp |
| US Virginia GCP | claude mcp add --transport http keboola https://mcp.us-east4.gcp.keboola.com/mcp |
| EU Frankfurt AWS | claude mcp add --transport http keboola https://mcp.eu-central-1.keboola.com/mcp |
| EU Ireland Azure | claude mcp add --transport http keboola https://mcp.north-europe.azure.keboola.com/mcp |
| EU Frankfurt GCP | claude mcp add --transport http keboola https://mcp.europe-west3.gcp.keboola.com/mcp |
Utilisation :
Une fois installé, vous pouvez utiliser le serveur MCP Keboola dans Claude Code en tapant /mcp dans votre conversation et en sélectionnant les outils Keboola que vous souhaitez utiliser.
Authentification :
Lorsque vous utilisez le serveur MCP Keboola pour la première fois dans Claude Code, une fenêtre de navigateur s'ouvrira vous invitant à :
- Vous connecter avec votre compte Keboola
- Sélectionner le projet auquel vous souhaitez vous connecter
- Autoriser la connexion
Après l'authentification, vous pouvez commencer à utiliser les outils Keboola directement depuis Claude Code.
Pour des instructions de configuration détaillées et des URL spécifiques à la région, consultez notre documentation de configuration du serveur distant.
Utilisation des branches de développement
Vous pouvez travailler en toute sécurité dans les branches de développement Keboola sans affecter vos données de production. Les serveurs MCP hébergés à distance respectent le paramètre KBC_BRANCH_ID et limiteront toutes les opérations à la branche spécifiée. Vous pouvez trouver l'ID de la branche de développement dans l'URL lorsque vous naviguez vers la branche de développement dans l'interface utilisateur, par exemple : https://connection.us-east4.gcp.keboola.com/admin/projects/PROJECT_ID/branch/BRANCH_ID/dashboard. L'ID de branche doit être inclus dans chaque requête en utilisant l'en-tête X-Branch-Id: <branchId>, sinon le serveur MCP utilise la branche de production par défaut. Cela doit être géré par le client IA ou l'environnement gérant la connexion au serveur.
Autorisation des outils et contrôle d'accès
Lors de l'utilisation de transports basés sur HTTP (HTTP Streamable), vous pouvez contrôler quels outils sont disponibles pour les clients à l'aide d'en-têtes HTTP. Ceci est utile pour restreindre les capacités de l'agent IA ou appliquer des politiques de conformité.
En-têtes d'autorisation
| En-tête | Description | Exemple |
|---|---|---|
X-Allowed-Tools | Liste séparée par des virgules des outils autorisés | get_configs,get_buckets,query_data |
X-Disallowed-Tools | Liste séparée par des virgules des outils à exclure | create_config,run_job |
X-Read-Only-Mode | Restreindre aux outils en lecture seule uniquement | true, 1, ou yes |
Comportement du filtre
Les filtres s'appliquent dans l'ordre : autorisés → intersection lecture seule → exclusion des interdits. En-têtes vides = aucune restriction.
Outils en lecture seule
Les outils en lecture seule sont ceux annotés avec readOnlyHint=True. Ces outils ne font que récupérer des informations sans apporter de modifications à votre projet Keboola. Pour la liste actuelle des outils en lecture seule, consultez le fichier TOOLS.md qui est un instantané généré automatiquement de l'ensemble d'outils réel.
Exemple : Accès en lecture seule
X-Read-Only-Mode: true
Pour une documentation détaillée, consultez developers.keboola.com/integrate/mcp/#tool-authorization-and-access-control.
Configuration du serveur MCP local (Méthode personnalisée ou de développement)
Exécutez le serveur MCP sur votre propre machine pour un contrôle total et un développement facile. Choisissez cette option lorsque vous souhaitez personnaliser les outils, déboguer localement ou itérer rapidement. Vous clonerez le dépôt, définirez les informations d'identification Keboola via des variables d'environnement ou des en-têtes selon le transport du serveur, installerez les dépendances et démarrerez le serveur. Cette approche offre une flexibilité maximale (outils personnalisés, journalisation locale, itération hors ligne) mais nécessite une configuration manuelle et vous gérez vous-même les mises à jour et les secrets.
Le serveur prend en charge plusieurs options de transport, qui peuvent être sélectionnées en fournissant l'argument --transport <transport> lors du démarrage du serveur :
stdio- Par défaut lorsque--transportn'est pas spécifié. Entrée/sortie standard, généralement utilisée pour le déploiement local avec un seul client.streamable-http- Exécute le serveur à distance via HTTP avec un canal de streaming bidirectionnel, permettant au client et au serveur d'échanger des messages en continu. Connectez-vous via /mcp (par exemple, http://localhost:8000/mcp).http-compat- Un alias pourstreamable-http, conservé pour la rétrocompatibilité.
Pour la communication client-serveur, les informations d'identification Keboola doivent être fournies pour permettre de travailler avec votre projet dans votre région Keboola. Les éléments suivants sont requis : KBC_STORAGE_TOKEN, KBC_STORAGE_API_URL, KBC_WORKSPACE_SCHEMA et optionnellement KBC_BRANCH_ID. Vous pouvez les fournir de deux manières :
- Pour un usage personnel (principalement avec le transport stdio) : définissez les variables d'environnement avant de démarrer le serveur. Toutes les requêtes réutiliseront ces informations d'identification prédéfinies.
- Pour un usage multi-utilisateurs : incluez les variables dans les en-têtes de requête afin que chaque requête utilise les informations d'identification fournies avec elle.
KBC_STORAGE_TOKEN
Il s'agit de votre jeton d'authentification pour Keboola :
Pour des instructions sur la création et la gestion des jetons d'API de stockage, reportez-vous à la documentation officielle de Keboola.
Remarque : Si vous souhaitez que le serveur MCP ait un accès limité, utilisez un jeton de stockage personnalisé ; si vous souhaitez que le MCP accède à tout dans votre projet, utilisez le jeton maître.
KBC_WORKSPACE_SCHEMA
Ceci identifie votre espace de travail dans Keboola et est utilisé pour les requêtes SQL. Cependant, ceci n'est requis que si vous utilisez un jeton de stockage personnalisé au lieu du jeton maître :
- Si vous utilisez le jeton maître : L'espace de travail est créé automatiquement en arrière-plan
- Si vous utilisez un jeton de stockage personnalisé : Suivez ce guide Keboola pour obtenir votre KBC_WORKSPACE_SCHEMA
Remarque : Lors de la création manuelle d'un espace de travail, cochez l'option "Accorder un accès en lecture seule à toutes les données du projet"
Remarque : KBC_WORKSPACE_SCHEMA est appelé "Nom du dataset" dans les espaces de travail BigQuery, il vous suffit de cliquer sur "connecter" et de copier le nom du dataset
KBC_STORAGE_API_URL (Région Keboola)
L'URL de l'API de votre région Keboola dépend de votre région de déploiement. Vous pouvez déterminer votre région en regardant l'URL dans votre navigateur lorsque vous êtes connecté à votre projet Keboola :
| Région | URL de l'API |
|---|---|
| AWS Amérique du Nord | https://connection.keboola.com |
| AWS Europe | https://connection.eu-central-1.keboola.com |
| Google Cloud EU | https://connection.europe-west3.gcp.keboola.com |
| Google Cloud US | https://connection.us-east4.gcp.keboola.com |
| Azure EU | https://connection.north-europe.azure.keboola.com |
KBC_BRANCH_ID (Optionnel)
Pour opérer sur une branche de développement Keboola spécifique, définissez l'ID de branche en utilisant le paramètre KBC_BRANCH_ID. Le serveur MCP limite ses fonctionnalités à la branche spécifiée, garantissant que toutes les modifications restent isolées et n'impactent pas la branche de production.
- S'il n'est pas fourni, le serveur utilise la branche de production par défaut.
- Pour le travail de développement, définissez
KBC_BRANCH_IDsur l'ID numérique de votre branche (par exemple,123456). Vous pouvez trouver l'ID de la branche de développement dans l'URL lorsque vous naviguez vers la branche de développement dans l'interface utilisateur, par exemple :https://connection.us-east4.gcp.keboola.com/admin/projects/PROJECT_ID/branch/BRANCH_ID/dashboard. - Sur les transports distants, vous pouvez remplacer par requête avec l'en-tête HTTP
X-Branch-Id: <branchId>ouKBC_BRANCH_ID: <branchId>.
Installation
Assurez-vous d'avoir :
- Python 3.10+ installé
- Accès à un projet Keboola avec des droits d'administration
- Votre client MCP préféré (Claude, Cursor, etc.)
Remarque : Assurez-vous d'avoir uv installé. Le client MCP l'utilisera pour télécharger et exécuter automatiquement le serveur MCP Keboola.
Installation de uv :
macOS/Linux :
#if homebrew is not installed on your machine use:
# /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# Install using Homebrew
brew install uv
Windows :
# Using the installer script
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# Or using pip
pip install uv
# Or using winget
winget install --id=astral-sh.uv -e
Pour plus d'options d'installation, consultez la documentation officielle de uv.
Exécution du serveur MCP Keboola
Il existe quatre façons d'utiliser le serveur MCP Keboola, selon vos besoins :
Option A : Mode intégré (Recommandé)
Dans ce mode, Claude ou Cursor démarre automatiquement le serveur MCP pour vous. Vous n'avez pas besoin d'exécuter de commandes dans votre terminal.
- Configurez votre client MCP (Claude/Cursor) avec les paramètres appropriés
- Le client lancera automatiquement le serveur MCP en cas de besoin
Configuration de Claude Desktop
- Allez dans Claude (coin supérieur gauche de votre écran) -> Paramètres → Développeur → Modifier la configuration (si vous ne voyez pas le claude_desktop_config.json, créez-le)
- Ajoutez la configuration suivante :
- Redémarrez Claude Desktop pour que les modifications prennent effet
{
"mcpServers": {
"keboola": {
"command": "uvx",
"args": ["keboola_mcp_server --transport <transport>"],
"env": {
"KBC_STORAGE_API_URL": "https://connection.YOUR_REGION.keboola.com",
"KBC_STORAGE_TOKEN": "your_keboola_storage_token",
"KBC_WORKSPACE_SCHEMA": "your_workspace_schema",
"KBC_BRANCH_ID": "your_branch_id_optional"
}
}
}
}
Emplacements des fichiers de configuration :
- macOS :
~/Library/Application Support/Claude/claude_desktop_config.json - Windows :
%APPDATA%\Claude\claude_desktop_config.json
Configuration de Cursor
- Allez dans Paramètres → MCP
- Cliquez sur "+ Ajouter un nouveau serveur MCP global"
- Configurez avec ces paramètres :
{
"mcpServers": {
"keboola": {
"command": "uvx",
"args": ["keboola_mcp_server --transport <transport>"],
"env": {
"KBC_STORAGE_API_URL": "https://connection.YOUR_REGION.keboola.com",
"KBC_STORAGE_TOKEN": "your_keboola_storage_token",
"KBC_WORKSPACE_SCHEMA": "your_workspace_schema",
"KBC_BRANCH_ID": "your_branch_id_optional"
}
}
}
}
Remarque : Utilisez des noms courts et descriptifs pour les serveurs MCP. Étant donné que le nom complet de l'outil inclut le nom du serveur et doit rester inférieur à ~60 caractères, les noms plus longs peuvent être filtrés dans Cursor et ne seront pas affichés à l'agent.
Configuration de Cursor pour Windows WSL
Lors de l'exécution du serveur MCP à partir du sous-système Windows pour Linux avec Cursor AI, utilisez cette configuration :
{
"mcpServers": {
"keboola":{
"command": "wsl.exe",
"args": [
"bash",
"-c '",
"export KBC_STORAGE_API_URL=https://connection.YOUR_REGION.keboola.com &&",
"export KBC_STORAGE_TOKEN=your_keboola_storage_token &&",
"export KBC_WORKSPACE_SCHEMA=your_workspace_schema &&",
"export KBC_BRANCH_ID=your_branch_id_optional &&",
"/snap/bin/uvx keboola_mcp_server --transport <transport>",
"'"
]
}
}
}
Option B : Mode de développement local
Pour les développeurs travaillant sur le code du serveur MCP lui-même :
- Clonez le dépôt et configurez un environnement local
- Configurez Claude/Cursor pour utiliser votre chemin Python local :
{
"mcpServers": {
"keboola": {
"command": "/absolute/path/to/.venv/bin/python",
"args": [
"-m",
"keboola_mcp_server --transport <transport>"
],
"env": {
"KBC_STORAGE_API_URL": "https://connection.YOUR_REGION.keboola.com",
"KBC_STORAGE_TOKEN": "your_keboola_storage_token",
"KBC_WORKSPACE_SCHEMA": "your_workspace_schema",
"KBC_BRANCH_ID": "your_branch_id_optional"
}
}
}
}
Option C : Mode CLI manuel (pour les tests uniquement)
Vous pouvez exécuter le serveur manuellement dans un terminal pour tester ou déboguer :
# Set environment variables
export KBC_STORAGE_API_URL=https://connection.YOUR_REGION.keboola.com
export KBC_STORAGE_TOKEN=your_keboola_storage_token
export KBC_WORKSPACE_SCHEMA=your_workspace_schema
export KBC_BRANCH_ID=your_branch_id_optional
uvx keboola_mcp_server --transport streamable-http
Remarque : Ce mode est principalement destiné au débogage ou aux tests. Pour une utilisation normale avec Claude ou Cursor, vous n'avez pas besoin d'exécuter le serveur manuellement.
Remarque : Le serveur utilisera le transport HTTP Streamable et écoutera sur
localhost:8000les connexions entrantes à/mcp. Vous pouvez utiliser les paramètres--portet--hostpour le faire écouter ailleurs.
Option D : Utilisation de Docker
docker pull keboola/mcp-server:latest
docker run \
--name keboola_mcp_server \
--rm \
-it \
-p 127.0.0.1:8000:8000 \
-e KBC_STORAGE_API_URL="https://connection.YOUR_REGION.keboola.com" \
-e KBC_STORAGE_TOKEN="YOUR_KEBOOLA_STORAGE_TOKEN" \
-e KBC_WORKSPACE_SCHEMA="YOUR_WORKSPACE_SCHEMA" \
-e KBC_BRANCH_ID="YOUR_BRANCH_ID_OPTIONAL" \
keboola/mcp-server:latest \
--transport streamable-http \
--host 0.0.0.0
Remarque : Le serveur utilisera le transport HTTP Streamable et écoutera sur
localhost:8000les connexions entrantes à/mcp. Vous pouvez modifier-ppour mapper le port du conteneur ailleurs.
Dois-je démarrer le serveur moi-même ?
| Scénario | Exécution manuelle nécessaire ? | Utilisez cette configuration |
|---|---|---|
| Utilisation de Claude/Cursor | Non | Configurer MCP dans les paramètres de l'application |
| Développement MCP en local | Non (Claude le démarre) | Pointer la configuration vers le chemin Python |
| Test CLI manuel | Oui | Utiliser le terminal pour exécuter |
| Utilisation de Docker | Oui | Exécuter le conteneur Docker |
Utilisation du serveur MCP
Une fois votre client MCP (Claude/Cursor) configuré et en cours d'exécution, vous pouvez commencer à interroger vos données Keboola :
Vérifiez votre configuration
Vous pouvez commencer par une requête simple pour confirmer que tout fonctionne :
What buckets and tables are in my Keboola project?
Exemples de ce que vous pouvez faire
Exploration des données :
- "Quelles tables contiennent des informations sur les clients ?"
- "Exécutez une requête pour trouver les 10 meilleurs clients par chiffre d'affaires"
Analyse des données :
- "Analysez mes données de ventes par région pour le dernier trimestre"
- "Trouvez des corrélations entre l'âge du client et la fréquence d'achat"
Pipelines de données :
- "Créez une transformation SQL qui joint les tables client et commande"
- "Démarrez le travail d'extraction de données pour mon composant Salesforce"
Compatibilité
Support des clients MCP
| Client MCP | Statut du support | Méthode de connexion |
|---|---|---|
| Claude (Desktop & Web) | ✅ supporté | stdio |
| Cursor | ✅ supporté | stdio |
| Windsurf, Zed, Replit | ✅ Supporté | stdio |
| Codeium, Sourcegraph | ✅ Supporté | HTTP Streamable |
| Clients MCP personnalisés | ✅ Supporté | HTTP Streamable ou stdio |
Outils supportés
Remarque : Vos agents IA s'adapteront automatiquement aux nouveaux outils.
Pour une liste complète des outils disponibles avec des descriptions détaillées, des paramètres et des exemples d'utilisation, consultez TOOLS.md.
Dépannage
Problèmes courants
| Problème | Solution |
|---|---|
| Erreurs d'authentification | Vérifiez que KBC_STORAGE_TOKEN est valide |
| Problèmes d'espace de travail | Confirmez que KBC_WORKSPACE_SCHEMA est correct |
| Délai de connexion dépassé | Vérifiez la connectivité réseau |
Développement
Installation
Configuration de base :
uv sync --extra dev
Avec la configuration de base, vous pouvez utiliser uv run tox pour exécuter les tests et vérifier le style du code.
Configuration recommandée :
uv sync --extra dev --extra tests --extra integtests --extra codestyle
Avec la configuration recommandée, les packages pour les tests et la vérification du style de code seront installés, ce qui permet aux IDE comme VsCode ou Cursor de vérifier le code ou d'exécuter les tests pendant le développement.
Tests d'intégration
Pour exécuter les tests d'intégration localement, utilisez uv run tox -e integtests.
REMARQUE : Vous devrez définir les variables d'environnement suivantes :
INTEGTEST_POOL_STORAGE_API_URLINTEGTEST_STORAGE_TOKENSINTEGTEST_STORAGE_TOKEN_STORAGE_BRANCHES
Afin d'obtenir ces valeurs, vous avez besoin de projets Keboola dédiés pour les tests d'intégration.
Chaque session de test crée son propre espace de travail en lecture seule, donc aucun schéma d'espace de travail n'a besoin d'être
configuré. Voir integtests/README.md pour des instructions de configuration détaillées et la documentation de conception.
Mise à jour de uv.lock
Mettez à jour le fichier uv.lock si vous avez ajouté ou supprimé des dépendances. Pensez également à mettre à jour le verrouillage avec des versions de dépendances plus récentes
lors de la création d'une version (uv lock --upgrade).
Mise à jour de la documentation des outils
Lorsque vous apportez des modifications aux descriptions des outils (docstrings dans les fonctions d'outils), vous devez régénérer le fichier de documentation TOOLS.md pour refléter ces changements :
uv run python -m src.keboola_mcp_server.generate_tool_docs
Publication
Nous ne publions pas de version pour chaque PR fusionnée. Le travail atterrit sur le tronc (main)
en continu, et nous publions périodiquement une fois que les modifications ont été retestées ensemble —
cela évite de casser les configurations de travail pour les utilisateurs.
Une version est créée en poussant un ou deux tags git :
vX.Y.Z— la version du serveur MCP (toujours)agent-vX.Y.Z— la version de l'agent In Platform (uniquement lorsque l'agent est également publié)
L'un ou l'autre tag déclenche release.yml CI, qui construit et publie l'image Docker. KaiBench
ne s'exécute que sur les tags de production vX.Y.Z (pas agent-vX.Y.Z, et pas les pré-versions -dev.). Utilisez
la compétence release-notes — elle prépare les notes de version et la PR brouillon et guide à travers
le taggage de vX.Y.Z et agent-vX.Y.Z.
Support et retours
⭐ Le principal moyen d'obtenir de l'aide, de signaler des bugs ou de demander des fonctionnalités est d'ouvrir une issue sur GitHub. ⭐
L'équipe de développement surveille activement les issues et répondra aussi rapidement que possible. Pour des informations générales sur Keboola, veuillez utiliser les ressources ci-dessous.
Ressources
- Documentation utilisateur
- Documentation développeur
- Plateforme Keboola
- Suivi des issues ← Méthode de contact principale pour le serveur MCP