Keboola MCP Server

officiel

Créez des workflows de données robustes, des intégrations et des analyses sur une plateforme intuitive unique.

Documentation

Ask DeepWiki

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

  1. Obtenez l'URL de votre serveur distant : Accédez aux paramètres de votre projet Keboola → onglet MCP Server
  2. Copiez l'URL du serveur : Elle ressemblera à https://mcp.<YOUR_REGION>.keboola.com/mcp
  3. Configurez votre assistant IA : Collez l'URL dans les paramètres MCP de votre assistant IA
  4. 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 Install MCP Server
  • 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égionCommande d'installation
US Virginia AWSclaude mcp add --transport http keboola https://mcp.keboola.com/mcp
US Virginia GCPclaude mcp add --transport http keboola https://mcp.us-east4.gcp.keboola.com/mcp
EU Frankfurt AWSclaude mcp add --transport http keboola https://mcp.eu-central-1.keboola.com/mcp
EU Ireland Azureclaude mcp add --transport http keboola https://mcp.north-europe.azure.keboola.com/mcp
EU Frankfurt GCPclaude 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 à :

  1. Vous connecter avec votre compte Keboola
  2. Sélectionner le projet auquel vous souhaitez vous connecter
  3. 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êteDescriptionExemple
X-Allowed-ToolsListe séparée par des virgules des outils autorisésget_configs,get_buckets,query_data
X-Disallowed-ToolsListe séparée par des virgules des outils à exclurecreate_config,run_job
X-Read-Only-ModeRestreindre aux outils en lecture seule uniquementtrue, 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 --transport n'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 pour streamable-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 :

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égionURL de l'API
AWS Amérique du Nordhttps://connection.keboola.com
AWS Europehttps://connection.eu-central-1.keboola.com
Google Cloud EUhttps://connection.europe-west3.gcp.keboola.com
Google Cloud UShttps://connection.us-east4.gcp.keboola.com
Azure EUhttps://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_ID sur 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> ou KBC_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.

  1. Configurez votre client MCP (Claude/Cursor) avec les paramètres appropriés
  2. Le client lancera automatiquement le serveur MCP en cas de besoin

Configuration de Claude Desktop

  1. 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)
  2. Ajoutez la configuration suivante :
  3. 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

  1. Allez dans Paramètres → MCP
  2. Cliquez sur "+ Ajouter un nouveau serveur MCP global"
  3. 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 :

  1. Clonez le dépôt et configurez un environnement local
  2. 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:8000 les connexions entrantes à /mcp. Vous pouvez utiliser les paramètres --port et --host pour 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:8000 les connexions entrantes à /mcp. Vous pouvez modifier -p pour mapper le port du conteneur ailleurs.

Dois-je démarrer le serveur moi-même ?

ScénarioExécution manuelle nécessaire ?Utilisez cette configuration
Utilisation de Claude/CursorNonConfigurer MCP dans les paramètres de l'application
Développement MCP en localNon (Claude le démarre)Pointer la configuration vers le chemin Python
Test CLI manuelOuiUtiliser le terminal pour exécuter
Utilisation de DockerOuiExé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 MCPStatut du supportMé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èmeSolution
Erreurs d'authentificationVérifiez que KBC_STORAGE_TOKEN est valide
Problèmes d'espace de travailConfirmez 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_URL
  • INTEGTEST_STORAGE_TOKENS
  • INTEGTEST_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

Connectez-vous