Keboola

Keboola MCP Server

Verbinde deine KI-Agenten, MCP-Clients (Cursor, Claude, Windsurf, VS Code ...) und andere KI-Assistenten mit Keboola. Stelle Daten, Transformationen, SQL-Abfragen und Job-Auslöser bereit – ganz ohne Glue-Code. Liefere Agenten die richtigen Daten, wann und wo sie sie benötigen.

Überblick

Keboola MCP Server ist eine Open-Source-Brücke zwischen deinem Keboola-Projekt und modernen KI-Tools. Sie macht Keboola-Funktionen – wie den Zugriff auf Storage, SQL-Transformationen und Job-Auslöser – zu aufrufbaren Tools für Claude, Cursor, CrewAI, LangChain, Amazon Q und mehr.

• Schnellstart
• Lokale Einrichtung

Funktionen

Mit dem AI Agent und MCP Server kannst du:

• Storage: Tabellen direkt abfragen und Tabellen- oder Bucket-Beschreibungen verwalten
• Komponenten: Extractors, Writers, Data Apps und Transformationskonfigurationen erstellen, auflisten und prüfen
• SQL: SQL-Transformationen in natürlicher Sprache erstellen
• Jobs: Komponenten und Transformationen ausführen und Details zur Job-Ausführung abrufen
• Flows: Workflow-Pipelines mit Conditional Flows und Orchestrator Flows erstellen und verwalten.
• Data Apps: Keboola Data Apps erstellen, bereitstellen und verwalten, die deine Abfragen über Storage-Daten anzeigen — python-js-Apps in einem von Keboola verwalteten Repository oder in einem GitHub-Repository des Kunden (über die GitHub-Verbindung der Organisation geklont, ohne gespeicherte Zugangsdaten) sowie Streamlit-Apps.
• Metadaten: Projektdokumentation und Objektmetadaten in natürlicher Sprache durchsuchen, lesen und aktualisieren
• Dev Branches: Sicher in Entwicklungs-Branches außerhalb der Produktion arbeiten, wobei alle Vorgänge auf den ausgewählten Branch beschränkt sind.

---

🚀 Schnellstart: Remote MCP Server (einfachster Weg)

Am einfachsten verwendest du Keboola MCP Server über unseren Remote MCP Server. Diese gehostete Lösung macht lokale Einrichtung, Konfiguration oder Installation überflüssig.

Was ist der Remote MCP Server?

Unser Remote Server wird auf jedem Multi-Tenant-Keboola-Stack gehostet und unterstützt OAuth-Authentifizierung. Du kannst dich von jedem KI-Assistenten aus damit verbinden, der Remote Streamable HTTP-Verbindungen und OAuth-Authentifizierung unterstützt.

Verbindung herstellen

1. Rufe die URL deines Remote Servers ab: Navigiere zu den Projekteinstellungen von Keboola → Tab MCP Server
2. Kopiere die Server-URL: Sie sieht etwa so aus: https://mcp.<YOUR_REGION>.keboola.com/mcp
3. Konfiguriere deinen KI-Assistenten: Füge die URL in den MCP-Einstellungen deines KI-Assistenten ein
4. Authentifiziere dich: Du wirst aufgefordert, dich mit deinem Keboola-Konto anzumelden. Welche(s) Projekt(e) verwendet werden soll(en), wird anschließend im Gespräch festgelegt (z. B. „list my Keboola projects“ / „use project X“)

Unterstützte Clients

• Cursor: Verwende die Schaltfläche „Install In Cursor“ in den MCP-Server-Einstellungen deines Projekts oder klicke auf diese Schaltfläche
• Claude Desktop: Füge die Integration über Einstellungen → Integrationen hinzu
• Claude Code: Installiere die Integration mit claude mcp add --transport http keboola <URL> (Details siehe unten)
• Windsurf: Konfiguriere den Client mit der URL des Remote Servers
• Make: Konfiguriere den Client mit der URL des Remote Servers
• Andere MCP-Clients: Konfiguriere den Client mit der URL des Remote Servers

Claude Code einrichten

Claude Code ist ein Befehlszeilenprogramm, mit dem du über dein Terminal mit Claude interagieren kannst. Du kannst die Keboola MCP Server-Integration mit einem einfachen Befehl installieren.

Installation:

Führe den folgenden Befehl in deinem Terminal aus und ersetze <YOUR_REGION> durch deine Keboola-Region:

claude mcp add --transport http keboola https://mcp.<YOUR_REGION>.keboola.com/mcp

Regionsspezifische Befehle:

Region	Installationsbefehl
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

Verwendung:

Nach der Installation kannst du Keboola MCP Server in Claude Code verwenden, indem du /mcp in deinem Gespräch eingibst und die Keboola-Tools auswählst, die du verwenden möchtest.

Authentifizierung:

Wenn du Keboola MCP Server zum ersten Mal in Claude Code verwendest, öffnet sich ein Browserfenster. Du wirst aufgefordert:

1. Dich mit deinem Keboola-Konto anzumelden
2. Die Verbindung zu autorisieren

Nach der Authentifizierung kannst du Keboola-Tools direkt in Claude Code verwenden. Die Projektauswahl erfolgt anschließend im Gespräch — frage Claude einfach, welche(s) Keboola-Projekt(e) verwendet werden soll(en).

Ausführliche Einrichtungsanweisungen und regionsspezifische URLs findest du in unserer Dokumentation zur Einrichtung des Remote Servers.

Entwicklungs-Branches verwenden

Du kannst sicher in Keboola-Entwicklungs-Branches arbeiten, ohne deine Produktionsdaten zu beeinträchtigen. Die gehosteten MCP Server berücksichtigen den Parameter KBC_BRANCH_ID und beschränken alle Vorgänge auf den angegebenen Branch. Die ID des Entwicklungs-Branches findest du in der URL, wenn du in der Benutzeroberfläche zum Entwicklungs-Branch navigierst, zum Beispiel: https://connection.us-east4.gcp.keboola.com/admin/projects/PROJECT_ID/branch/BRANCH_ID/dashboard. Die Branch-ID muss bei jeder Anfrage im Header X-Branch-Id: <branchId> enthalten sein. Andernfalls verwendet der MCP Server standardmäßig den Produktions-Branch. Dies sollte vom KI-Client oder der Umgebung verwaltet werden, die die Serververbindung handhabt.

Tool-Autorisierung und Zugriffskontrolle

Bei HTTP-basierten Transporten (Streamable HTTP) kannst du über HTTP-Header steuern, welche Tools Clients zur Verfügung stehen. Das ist nützlich, um die Fähigkeiten von KI-Agenten einzuschränken oder Compliance-Richtlinien durchzusetzen.

Autorisierungs-Header

Header	Beschreibung	Beispiel
X-Allowed-Tools	Durch Kommas getrennte Liste zulässiger Tools	get_configs,get_buckets,query_data
X-Disallowed-Tools	Durch Kommas getrennte Liste auszuschließender Tools	create_config,run_job
X-Read-Only-Mode	Beschränkt die verfügbaren Tools auf schreibgeschützte Tools	true, 1 oder yes

Filterverhalten

Filter werden in dieser Reihenfolge angewendet: zulässige Tools → Schnittmenge mit schreibgeschützten Tools → ausgeschlossene Tools. Leere Header bedeuten keine Einschränkung.

Schreibgeschützte Tools

Schreibgeschützte Tools sind mit readOnlyHint=True gekennzeichnet. Diese Tools rufen nur Informationen ab und nehmen keine Änderungen an deinem Keboola-Projekt vor. Die aktuelle Liste schreibgeschützter Tools findest du in der Datei TOOLS.md, einem automatisch generierten Snapshot des tatsächlichen Tool-Sets.

Beispiel: Schreibgeschützter Zugriff

X-Read-Only-Mode: true

Verzögertes Laden von Tools

Header	Beschreibung	Beispiel
X-Deferred-Tools	Durch Kommas getrennte Liste der Tools, die mit _meta["anthropic/alwaysLoad"] = false aufgelistet werden sollen	run_sync_action,get_flow_schema

Claude Code- und Claude Agent SDK-Clients, die den Server mit alwaysLoad: true registrieren, halten diese Tools hinter der Tool-Suche zurück, anstatt ihre Definitionen sofort zu laden. Der Header ändert nur die Metadaten von tools/list — er blendet Tools weder aus noch autorisiert er sie. Ein leerer Header oder unbekannte Tool-Namen bewirken keine Änderung.

Ausführliche Dokumentation findest du unter developers.keboola.com/integrate/mcp/#tool-authorization-and-access-control.

Sicherheit auf Zeilen- und Spaltenebene

Richtlinien auf Zeilen- und Spaltenebene sind Keboola-Metastore-Objekte (rls-policy, cls-policy), die mit kbagent rls / kbagent cls erstellt werden. Dieser Server liest sie weder aus noch wendet er sie an. In einem Projekt mit aktivierter Funktion row-level-security erstellt er seinen Workspace (die Konfiguration mcp-workspace-<hex> der Komponente keboola.mcp-server-tool) mit dem Verbindungstyp governed. Ein verwalteter Workspace hat keine Zugangsdaten: Nur der Query Service kann ihn lesen, und der Query Service filtert jedes Ergebnis von query_data anhand der Richtlinien des Projekts. Dieser Server schreibt keine Abfragen um und bietet keinen Fallback: Was der Query Service verweigert, gibt query_data als Fehler zurück.

• Was die Funktion aktiviert. Dieser Server prüft die Projektfunktion; für das Erstellen eines verwalteten Workspaces benötigt Connection weder eine Funktion noch eine Rolle (Snowflake oder BigQuery, kein öffentlicher Schlüssel). Connection des Stacks muss den Verbindungstyp governed für das Backend des Projekts akzeptieren: Ein Stack, der dies nicht unterstützt, verweigert die Erstellung. Danach schlagen alle Tools fehl, die den Workspace benötigen (es gibt keinen Fallback auf einen gewöhnlichen Workspace). Ein älterer gewöhnlicher MCP-Workspace wird nicht gelöscht: Sobald die Funktion aktiviert ist, wird er übersprungen. Bei aktivierter Funktion wird ein workspace_schema oder X-Workspace-Id nur für einen verwalteten Workspace akzeptiert (ein gewöhnlicher Workspace würde die Richtlinien umgehen). Daher wird eine Bindung an den alten Workspace oder an den eigenen gewöhnlichen Workspace einer Data App verweigert; lösche den alten Workspace.
• Standardmäßig verweigern. Der Query Service verweigert den Zugriff auf eine Tabelle in einem verwalteten Workspace, auf die keine rls-policy zutrifft (eine Regel vom Typ "*" gibt allen identifizierten Lesern Zugriff auf eine Tabelle); ein cls-policy allein gewährt keine Zeilen. Eine Anweisung, die keine Tabelle liest (SELECT 1), wird ausgeführt. Eine Verweigerung wird dem Agenten als Row-level security does not allow this query gemeldet.
• Wer der Leser ist. Der Query Service ermittelt den Leser anhand des eigenen Tokens des Administrators für das Projekt: des programmgesteuerten Tokens, das dieser Server weiterleitet (kbc_at_ / kbc_pat_, einschließlich des untergeordneten PAT eines Multi-Projekt-Bereichs, gesendet mit X-KBC-ProjectId), oder des eigenen Master-Storage-Tokens eines Administrators. Jedes andere Token (eine Integration, eine Data App, Kai) identifiziert keinen Endbenutzer, hat keine verifizierte Identität und kann keine verwaltete Tabelle lesen. Gruppenregeln treffen nie zu (die Identität enthält keine Gruppen).
• Bindungen. Ohne Bindung erhält ein Workspace alle Richtlinien des Projekts; dieser Server erstellt niemals eine Bindung. Um einem Workspace nur bestimmte Richtlinien zuzuweisen, binde sie an seine KID: KID:<stack id>:project-<project id>:workspace-<workspace id> (ein Workspace des Standard-Branches; bei einem Branch-Workspace außerdem branch-<branch id> vor project). Die Stack-ID ist diejenige, mit der der Query Service konfiguriert ist (QUERY_RLS_STACK_ID, zum Beispiel dev-keboola-aws-eu-west-1), die Workspace-ID steht in der Ausgabe von get_project_info, und kbagent rls bind --project P --workspace-id WS --rls-policy ID --stack-id S schreibt die Bindung. Eine Bindung schränkt nur ein, gilt für die nächste Abfrage und wird nicht auf eine andere Workspace-Sitzung übertragen: Eine Branch-Sitzung oder ein neu erstellter Workspace hat eine neue KID und erhält wieder alle Richtlinien.
• Einschränkungen. Die Workspace-ID des Server-Workspaces ist auch diejenige, die eine Data App als WORKSPACE_ID erhält, wenn kein separater Workspace für sie bereitgestellt wird. Die App fragt mit ihrem eigenen Token ab, hat keine verifizierte Identität und kann keine verwalteten Tabellen lesen.
• Metadaten. Die Metadaten-Tools zeigen nur, was der Query Service dem Leser zugänglich macht. get_tables und search (das dann nicht die globale Suche verwendet, da deren Zählungen auch ausgeblendete Tabellen umfassen) lassen Tabellen aus, die der Leser nicht lesen darf. get_tables meldet eine anhand ihrer ID angeforderte Tabelle als nicht gefunden. Bei einer Tabelle mit Spaltenrichtlinie werden nur die Spalten der Richtlinie angezeigt (auch im Primärschlüssel und bei den Treffern von search). Eine lesbare Tabelle wird ohne Zeilenanzahl und Größe angezeigt, da diese die von einer Zeilenrichtlinie ausgeblendeten Zeilen mitzählen. get_buckets listet weiterhin alle Buckets auf, jedoch ohne Tabellenanzahl und Größe, da diese die ausgeblendeten Tabellen mitzählen. Dafür ist der Query-Service-Endpunkt POST /api/v1/branches/{branch}/workspaces/{workspace}/rls/scope erforderlich. Die Verarbeitung schlägt geschlossen fehl: Kann der Query Service keine Auskunft geben, gibt ein Tool eines verwalteten Projekts einen Fehler mit einer kurzen Meldung und ohne Tabelle zurück. Projekte ohne aktivierte Funktion sind nicht betroffen und lösen keinen zusätzlichen Aufruf aus.

---

Lokale Einrichtung des MCP Servers (benutzerdefinierter oder Entwicklungsmodus)

Führe den MCP Server auf deinem eigenen Rechner aus, um die volle Kontrolle zu haben und einfach entwickeln zu können. Wähle diese Option, wenn du Tools anpassen, lokal debuggen oder schnell iterieren möchtest. Du installierst den Server, authentifizierst dich (einmalige Browser-Anmeldung — kein Token zum Einfügen) und startest ihn. Dieser Ansatz bietet maximale Flexibilität (benutzerdefinierte Tools, lokale Protokollierung, Offline-Iteration), erfordert aber eine manuelle Einrichtung; Updates und Geheimnisse verwaltest du selbst. Der Server unterstützt mehrere Transport-Optionen, die beim Starten des Servers mit dem Argument --transport <transport> ausgewählt werden können:

• stdio – Standard, wenn --transport nicht angegeben ist. Standardeingabe/-ausgabe, typischerweise für lokale Bereitstellungen mit einem einzelnen Client verwendet.
• streamable-http – Führt den Server remote über HTTP mit einem bidirektionalen Streaming-Kanal aus, über den Client und Server kontinuierlich Nachrichten austauschen können. Verbindung über /mcp (z. B. http://localhost:8000/mcp).
• http-compat – Ein Alias für streamable-http, der aus Gründen der Abwärtskompatibilität beibehalten wird.

Damit der Server mit Ihrem Keboola-Projekt arbeiten kann, benötigt er zwei Dinge: Ihre Keboola-Region (KBC_STORAGE_API_URL) und eine Möglichkeit zur Authentifizierung. Empfohlen wird eine einmalige Anmeldung im Browser – Sie müssen niemals ein Token erstellen, kopieren oder einfügen. Optional können Sie KBC_BRANCH_ID festlegen, um in einem Entwicklungsbranch zu arbeiten.

Einige Variablen werden nicht aus den Request-Headern übernommen:

• KBC_STORAGE_API_URL: Ein Server, der mit einer eigenen Storage-API-URL gestartet wurde (dem Parameter --api-url oder der Umgebungsvariable KBC_STORAGE_API_URL), bedient nur diesen einen Keboola-Stack. Ein X-Storage-Api-Url-Header, der einen anderen Host anfordert, wird ignoriert (eine Warnung wird protokolliert) – der Server verwendet für den Request weiterhin seine eigene URL. Starten Sie den Server ohne eigene Storage-API-URL, wenn jeder Request seinen Stack auswählen können soll.
• KBC_KUBERNETES_TOKEN_PATH (nur bereitgestellte Server, siehe docs/kubernetes-sa-auth.md): Wird nur aus der Umgebung gelesen, niemals aus einem Header.
• KBC_WORKSPACE_ID / KBC_WORKSPACE_SCHEMA: Wie bei der Storage-API-URL oben gilt: Ein Server, der mit einer eigenen Workspace-Festlegung gestartet wurde (über eine der beiden Variablen oder --workspace-id), behält diese Festlegung für jeden Request bei. Ein X-Workspace-Id- oder X-Workspace-Schema-Header, der einen anderen Workspace anfordert, wird ignoriert (eine Warnung wird protokolliert). Ein Server ohne eigene Festlegung (der gemeinsam genutzte Mehrbenutzerfall) übernimmt die Festlegung weiterhin für jeden Request aus der Anfrage, wie unten beschrieben.

Anmelden

Melden Sie sich einmal im Browser an. Der Server speichert die Sitzung und aktualisiert sie automatisch, sodass keine Tokens verwaltet werden müssen:

uvx keboola_mcp_server login --api-url https://connection.YOUR_REGION.keboola.com

Dadurch wird Ihr Browser geöffnet, um sich bei Keboola anzumelden. Anschließend wird die stackweite Sitzung unter ~/.keboola/mcp/credentials.json gespeichert (nur für Sie lesbar, ein Eintrag pro Stack). Starten Sie den Server danach nur mit gesetztem KBC_STORAGE_API_URL – ein Token ist nicht erforderlich. Welche Projekte verwendet werden sollen, wird anschließend im Gespräch festgelegt (get_accessible_projects / set_project_scope), nicht während der Anmeldung.

Befehl	Funktion
login --api-url <url>	Bei einem Stack anmelden
login --force	Erneut anmelden / Konto wechseln
login --show-token	Aktuelles Sitzungstoken ausgeben (Debugging)
logout [--api-url <url>] [--all]	Gespeicherte Sitzung für einen Stack (oder alle Stacks) entfernen

Wenn Sie den Server über stdio in einem interaktiven Terminal starten und keine Sitzung gespeichert ist, führt er diese Browseranmeldung beim ersten Start automatisch aus. MCP-Clients (Claude, Cursor, …) starten den Server im Hintergrund, wo kein Browser geöffnet werden kann. Führen Sie daher zuerst einmal selbst login aus.

Ohne Keboola-Konto starten

Sie können den Server auch nur mit KBC_STORAGE_API_URL und ganz ohne Anmeldedaten starten. Er wird im Bootstrap-Modus gestartet: Tools, die Keboola-Zugriff benötigen, erklären, wie Sie Anmeldedaten erhalten, und ein Tool funktioniert ohne diese – create_project. Es erstellt ein neues Keboola-Projekt, meldet die Sitzung dort an und gibt eine Bestätigungs-URL zurück. Wenn Sie diese URL in einem Browser öffnen und sich anmelden, gehört das Projekt dauerhaft Ihnen. Bis dahin ist es temporär und Keboola kann es zurückfordern. Nach der Bestätigung wird die vom Tool erstellte Sitzung widerrufen, und Sie arbeiten mit Ihrem eigenen login weiter.

Dafür ist ein Stack mit aktivierter Agent-Bereitstellung erforderlich. Andernfalls meldet das Tool, dass es nicht verfügbar ist.

Dasselbe ist auch ohne eigenen Server möglich: auf einem remote gehosteten MCP-Server, dessen Betreiber diese Funktion aktiviert hat (KBC_ALLOW_ANONYMOUS_PROVISIONING). Eine solche Bereitstellung stellt ebenfalls https://mcp.<stack>/mcp-anonymous bereit, das keine Anmeldedaten akzeptiert. Richten Sie Ihren Client ohne Authentifizierung darauf aus, rufen Sie create_project auf und arbeiten Sie anschließend in dem durch diesen Aufruf erstellten Projekt weiter – der Server verwahrt die Anmeldedaten für Sie, und das Tool gibt ein undurchsichtiges scope_token zurück, das bei späteren Aufrufen erneut gesendet werden muss. Dafür gibt es eine separate URL, weil der normale /mcp-Endpunkt nicht authentifizierte Requests weiterhin ablehnen muss: An dieser Ablehnung erkennen MCP-Clients, dass sie die OAuth-Anmeldung starten sollen. Sobald Sie das Projekt übernommen haben, wechseln Sie zu /mcp und melden sich mit dem Konto an, dem es nun gehört.

Authentifizierung ohne Browser

Für Container oder CI-Umgebungen, in denen keine Browseranmeldung möglich ist, geben Sie direkt ein Keboola-Zugriffs- oder persönliches Zugriffstoken an – setzen Sie KBC_STORAGE_TOKEN (Umgebungsvariable) oder senden Sie den Header X-StorageAPI-Token – und zusätzlich KBC_PROJECT_ID (oder den Header X-KBC-ProjectId), um das Projekt auszuwählen. Bei HTTP-Transporten können diese Werte pro Request als Header übergeben werden, sodass jeder Request seine eigenen Anmeldedaten enthält.

KBC_WORKSPACE_ID

Leitet Abfragen anhand der ID an einen bestimmten, bereits vorhandenen Workspace weiter, statt die oben beschriebene schemabasierte Suche zu verwenden. Wenn beide gesetzt sind, hat diese Option Vorrang vor KBC_WORKSPACE_SCHEMA. Diese Option wird von einem Data-App- / kai-agent-Aufrufer als Header X-Workspace-Id übergeben, damit Kai, eingebettet in diese App, Abfragen ausschließlich über den eigenen Workspace ausführt.

Festlegen können Sie die ID über die Umgebungsvariable KBC_WORKSPACE_ID, das CLI-Flag --workspace-id oder (pro Request bei Mehrbenutzerbereitstellungen) den Header X-Workspace-Id.

KBC_STORAGE_API_URL (Keboola-Region)

Die API-URL Ihrer Keboola-Region hängt von Ihrer Bereitstellungsregion ab. Ihre Region können Sie anhand der URL ermitteln, die im Browser angezeigt wird, wenn Sie bei Ihrem Keboola-Projekt angemeldet sind:

Region	API-URL
AWS North America	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 (optional)

Um in einem bestimmten Keboola-Entwicklungsbranch zu arbeiten, legen Sie die Branch-ID mit dem Parameter KBC_BRANCH_ID fest. Der MCP-Server beschränkt seine Funktionen auf den angegebenen Branch. Dadurch bleiben alle Änderungen isoliert und wirken sich nicht auf den Produktionsbranch aus.

• Wenn nicht angegeben, verwendet der Server standardmäßig den Produktionsbranch.
• Legen Sie für Entwicklungsarbeiten KBC_BRANCH_ID auf die numerische ID Ihres Branches fest (z. B. 123456). Die ID des Entwicklungsbranches finden Sie in der URL, wenn Sie in der Benutzeroberfläche zum Entwicklungsbranch navigieren, zum Beispiel: https://connection.us-east4.gcp.keboola.com/admin/projects/PROJECT_ID/branch/BRANCH_ID/dashboard.
• Bei Remote-Transporten können Sie den Wert pro Request mit dem HTTP-Header X-Branch-Id: <branchId> oder KBC_BRANCH_ID: <branchId> überschreiben.

Installation

Stellen Sie sicher, dass Folgendes vorhanden ist:

• Python 3.11+ ist installiert
• Zugriff auf ein Keboola-Projekt mit Administratorrechten
• Ihr bevorzugter MCP-Client (Claude, Cursor usw.)

Hinweis: Stellen Sie sicher, dass uv installiert ist. Der MCP-Client verwendet es, um den Keboola MCP Server automatisch herunterzuladen und auszuführen. uv installieren:

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

Weitere Installationsoptionen finden Sie in der offiziellen uv-Dokumentation.

Keboola MCP Server ausführen

Je nach Bedarf gibt es vier Möglichkeiten, den Keboola MCP Server zu verwenden:

Option A: Integrierter Modus (empfohlen)

In diesem Modus startet Claude oder Cursor den MCP-Server automatisch für Sie.

1. Melden Sie sich einmal in einem Terminal an, damit eine Sitzung gespeichert wird (der Client startet den Server im Hintergrund, wo kein Browser geöffnet werden kann):

   uvx keboola_mcp_server login --api-url https://connection.YOUR_REGION.keboola.com
   

2. Konfigurieren Sie Ihren MCP-Client (Claude/Cursor) mit den folgenden Einstellungen – nur KBC_STORAGE_API_URL wird benötigt.
3. Der Client startet den MCP-Server bei Bedarf automatisch.

Claude Desktop konfigurieren

1. Öffnen Sie Claude (oben links auf dem Bildschirm) -> Settings → Developer → Edit Config (wenn claude_desktop_config.json nicht angezeigt wird, erstellen Sie die Datei)
2. Fügen Sie die folgende Konfiguration hinzu:
3. Starten Sie Claude Desktop neu, damit die Änderungen wirksam werden.

{
  "mcpServers": {
    "keboola": {
      "command": "uvx",
      "args": ["keboola_mcp_server --transport <transport>"],
      "env": {
        "KBC_STORAGE_API_URL": "https://connection.YOUR_REGION.keboola.com",
        "KBC_BRANCH_ID": "your_branch_id_optional"
      }
    }
  }
}

Speicherorte der Konfigurationsdatei:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Cursor konfigurieren

1. Öffnen Sie Settings → MCP
2. Klicken Sie auf „+ Add new global MCP Server“
3. Konfigurieren Sie die folgenden Einstellungen:

{
  "mcpServers": {
    "keboola": {
      "command": "uvx",
      "args": ["keboola_mcp_server --transport <transport>"],
      "env": {
        "KBC_STORAGE_API_URL": "https://connection.YOUR_REGION.keboola.com",
        "KBC_BRANCH_ID": "your_branch_id_optional"
      }
    }
  }
}

Hinweis: Verwenden Sie kurze, aussagekräftige Namen für MCP-Server. Da der vollständige Toolname den Servernamen enthält und weniger als etwa 60 Zeichen lang sein muss, werden längere Namen in Cursor möglicherweise herausgefiltert und dem Agent nicht angezeigt.

Cursor unter Windows WSL konfigurieren

Wenn Sie den MCP-Server mit Cursor AI aus dem Windows-Subsystem für Linux ausführen, verwenden Sie diese Konfiguration:

{
  "mcpServers": {
    "keboola":{
      "command": "wsl.exe",
      "args": [
          "bash",
          "-c '",
          "export KBC_STORAGE_API_URL=https://connection.YOUR_REGION.keboola.com &&",
          "export KBC_BRANCH_ID=your_branch_id_optional &&",
          "/snap/bin/uvx keboola_mcp_server --transport <transport>",
          "'"
      ]
    }
  }
}

Option B: Lokaler Entwicklungsmodus

Für Entwickler, die am MCP-Server-Code selbst arbeiten:

1. Klonen Sie das Repository und richten Sie eine lokale Umgebung ein.
2. Konfigurieren Sie Claude/Cursor so, dass der lokale Python-Pfad verwendet wird:

{
  "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_BRANCH_ID": "your_branch_id_optional"
      }
    }
  }
}

Option C: Manueller CLI-Modus (nur zum Testen)

Sie können den Server zum Testen oder Debuggen manuell in einem Terminal ausführen:

# Sign in once (stores a session under ~/.keboola/mcp), then start the server.
export KBC_STORAGE_API_URL=https://connection.YOUR_REGION.keboola.com
uvx keboola_mcp_server login --api-url "$KBC_STORAGE_API_URL"

uvx keboola_mcp_server --transport streamable-http

Hinweis: Dieser Modus ist hauptsächlich für Debugging oder Tests gedacht. Für die normale Verwendung mit Claude oder Cursor müssen Sie den Server nicht manuell ausführen.

Hinweis: Der Server verwendet den Streamable-HTTP-Transport und lauscht unter localhost:8000 auf eingehende Verbindungen unter /mcp. Mit den Parametern --port und --host können Sie andere Werte festlegen.

Option D: Docker verwenden

Ein Container kann keinen Browser öffnen. Authentifizieren Sie sich daher mit einem Token (siehe Authentifizierung ohne Browser): Setzen Sie KBC_STORAGE_TOKEN auf ein Keboola-Zugriffs- oder persönliches Zugriffstoken und KBC_PROJECT_ID auf das Zielprojekt. (Bei HTTP können Sie stattdessen pro Request die Header X-StorageAPI-Token / X-KBC-ProjectId übergeben und diese Variablen weglassen.)

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_TOKEN" \
  -e KBC_PROJECT_ID="YOUR_PROJECT_ID" \
  -e KBC_BRANCH_ID="YOUR_BRANCH_ID_OPTIONAL" \
  keboola/mcp-server:latest \
  --transport streamable-http \
  --host 0.0.0.0

Hinweis: Der Server verwendet den Streamable-HTTP-Transport und lauscht unter localhost:8000 auf eingehende Verbindungen unter /mcp. Sie können -p ändern, um den Container-Port an einer anderen Stelle abzubilden.

Muss ich den Server selbst starten?

Szenario	Manuell ausführen?	Diese Einrichtung verwenden
Claude/Cursor verwenden	Nein	MCP in den App-Einstellungen konfigurieren
Lokal am MCP entwickeln	Nein (Claude startet ihn)	Konfiguration auf den Python-Pfad verweisen lassen
CLI manuell testen	Ja	Im Terminal ausführen
Docker verwenden	Ja	Docker-Container ausführen

MCP-Server verwenden

Sobald Ihr MCP-Client (Claude/Cursor) konfiguriert ist und läuft, können Sie Ihre Keboola-Daten abfragen:

Einrichtung überprüfen

Beginnen Sie mit einer einfachen Abfrage, um zu prüfen, ob alles funktioniert:

What buckets and tables are in my Keboola project?

Beispiele für mögliche Aufgaben

Daten erkunden:

• „Welche Tabellen enthalten Kundeninformationen?“
• „Führe eine Abfrage aus, um die 10 umsatzstärksten Kunden zu finden.“

Daten analysieren:

• „Analysiere meine Verkaufsdaten nach Region für das letzte Quartal.“
• „Finde Zusammenhänge zwischen dem Alter der Kunden und der Kaufhäufigkeit.“

Datenpipelines:

• „Erstelle eine SQL-Transformation, die Kunden- und Bestelltabellen verknüpft.“
• „Starte den Datenextraktionsjob für meine Salesforce-Komponente.“

Kompatibilität

Unterstützung von MCP-Clients

MCP-Client	Unterstützungsstatus	Verbindungsmethode
Claude (Desktop & Web)	✅ unterstützt	stdio
Cursor	✅ unterstützt	stdio
Windsurf, Zed, Replit	✅ Unterstützt	stdio
Codeium, Sourcegraph	✅ Unterstützt	Streamable HTTP
Benutzerdefinierte MCP-Clients	✅ Unterstützt	Streamable HTTP oder stdio

Unterstützte Tools

Hinweis: Ihre KI-Agenten passen sich automatisch an neue Tools an.

Eine vollständige Liste der verfügbaren Tools mit ausführlichen Beschreibungen, Parametern und Anwendungsbeispielen finden Sie unter TOOLS.md.

Fehlerbehebung

Häufige Probleme

Problem	Lösung
Authentifizierungsfehler	keboola_mcp_server login erneut ausführen (oder bei Authentifizierung mit einem Token das Token und KBC_PROJECT_ID überprüfen)
Verbindungs-Timeout	Netzwerkverbindung überprüfen

Entwicklung

Installation

Grundlegende Einrichtung:

uv sync --extra dev

Mit der grundlegenden Einrichtung kannst du uv run tox verwenden, um Tests auszuführen und den Code-Stil zu überprüfen.

Empfohlene Einrichtung:

uv sync --extra dev --extra tests --extra integtests --extra codestyle

Bei der empfohlenen Einrichtung werden Pakete für Tests und die Überprüfung des Code-Stils installiert. Dadurch können IDEs wie VsCode oder Cursor den Code überprüfen oder während der Entwicklung Tests ausführen.

Integrationstests

Um Integrationstests lokal auszuführen, verwende uv run tox -e integtests. HINWEIS: Du musst die folgenden Umgebungsvariablen festlegen:

• INTEGTEST_POOL_STORAGE_API_URL
• INTEGTEST_STORAGE_TOKENS
• INTEGTEST_STORAGE_TOKEN_STORAGE_BRANCHES

Um diese Werte zu erhalten, benötigst du dedizierte Keboola-Projekte für Integrationstests. Jede Testsitzung erstellt einen eigenen schreibgeschützten Arbeitsbereich, daher muss kein Arbeitsbereichsschema konfiguriert werden. Detaillierte Einrichtungsanweisungen und Designdokumentation findest du unter integtests/README.md.

uv.lock aktualisieren

Aktualisiere die Datei uv.lock, wenn du Abhängigkeiten hinzugefügt oder entfernt hast. Ziehe außerdem in Betracht, die Sperrdatei bei der Erstellung eines Releases mit neueren Abhängigkeitsversionen zu aktualisieren (uv lock --upgrade).

Tool-Dokumentation aktualisieren

Wenn du Änderungen an Beschreibungen von Tools vornimmst (Docstrings in Tool-Funktionen), musst du die Dokumentationsdatei TOOLS.md neu generieren, damit diese Änderungen berücksichtigt werden:

uv run python -m src.keboola_mcp_server.generate_tool_docs

Release erstellen

Wir erstellen nicht für jeden zusammengeführten PR ein Release. Änderungen werden kontinuierlich in den Trunk (main) übernommen. Releases erstellen wir regelmäßig, sobald die Änderungen gemeinsam erneut getestet wurden — so vermeiden wir, funktionierende Setups für Nutzer zu beeinträchtigen.

Ein Release wird durch das Pushen von einem oder zwei Git-Tags erstellt:

• vX.Y.Z — das MCP-Server-Release (immer)
• agent-vX.Y.Z — das In Platform Agent-Release (nur, wenn auch der Agent veröffentlicht wird)

Jeder der beiden Tags löst release.yml CI aus, das das Docker-Image erstellt und veröffentlicht. KaiBench wird nur bei Produktions-Tags vX.Y.Z ausgeführt (nicht bei agent-vX.Y.Z und nicht bei -dev.-Vorabversionen). Verwende den Skill release-notes — er erstellt die Release Notes und einen PR-Entwurf und führt dich durch das Tagging von vX.Y.Z und agent-vX.Y.Z.

Support und Feedback

⭐ Der wichtigste Weg, Hilfe zu erhalten, Fehler zu melden oder Funktionen anzufragen, ist ein Issue auf GitHub zu eröffnen. ⭐

Das Entwicklungsteam verfolgt Issues aktiv und antwortet so schnell wie möglich. Allgemeine Informationen zu Keboola findest du in den folgenden Ressourcen.

Ressourcen

• Benutzerdokumentation
• Entwicklerdokumentation
• Keboola-Plattform
• Issue-Tracker ← Primäre Kontaktmöglichkeit für den MCP Server

Verbinden

• LinkedIn
• Twitter
• Changelog