Potencia tu agente
La URL propia del publicador. No es un endpoint de PlugMCP.
Host a copy with our keys and logs.
https://mcp.us-east4.gcp.keboola.com/mcpEl botón de Claude de arriba abre Claude con el nombre y la URL ya rellenados. Aún tienes que confirmarlo allí.
claude mcp add --transport http keboola-mcp-server https://mcp.us-east4.gcp.keboola.com/mcpRun in a terminal.
{ "mcpServers": { "keboola-mcp-server": { "command": "npx", "args": [ "-y", "mcp-remote", "https://mcp.us-east4.gcp.keboola.com/mcp" ] } }}claude_desktop_config.json
¿URL remota o un comando en tu máquina? En qué se diferencian las dos instalaciones
Ejecutar en PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
AbrirDel publicador
Connect your AI agents, MCP clients (Cursor, Claude, Windsurf, VS Code ...) and other AI assistants to Keboola. Expose data, transformations, SQL queries, and job triggers—no glue code required. Deliver the right data to agents when and where they need it.
Model Context Protocol (MCP) Server for the Keboola Platform
Keboola MCP Server is an open-source bridge between your Keboola project and modern AI tools. It turns Keboola features—like storage access, SQL transformations, and job triggers—into callable tools for Claude, Cursor, CrewAI, LangChain, Amazon Q, and more.
With the AI Agent and MCP Server, you can:
The easiest way to use Keboola MCP Server is through our Remote MCP Server. This hosted solution eliminates the need for local setup, configuration, or installation.
Our remote server is hosted on every multi-tenant Keboola stack and supports OAuth authentication. You can connect to it from any AI assistant that supports remote Streamable HTTP connection and OAuth authentication.
MCP Server tabhttps://mcp.<YOUR_REGION>.keboola.com/mcp
claude mcp add --transport http keboola <URL> (see below for details)Claude Code is a command-line interface tool that allows you to interact with Claude using your terminal. You can install the Keboola MCP Server integration using a simple command.
Installation:
Run the following command in your terminal, replacing <YOUR_REGION> with your Keboola region:
claude mcp add --transport http keboola https://mcp.<YOUR_REGION>.keboola.com/mcp
Region-specific commands:
Usage:
Once installed, you can use the Keboola MCP Server in Claude Code by typing /mcp in your conversation and selecting the Keboola tools you want to use.
Authentication:
When you first use the Keboola MCP Server in Claude Code, a browser window will open prompting you to:
After authentication, you can start using Keboola tools directly from Claude Code. Project selection happens afterward, in the conversation — just ask Claude which Keboola project(s) to use.
For detailed setup instructions and region-specific URLs, see our Remote Server Setup documentation.
You can work safely in Keboola development branches without affecting your production data. The remotely hosted MCP Servers respect the KBC_BRANCH_ID parameter and will scope all operations to the specified branch. You can find the development branch ID in the URL when navigating to the development branch in the UI, for example: https://connection.us-east4.gcp.keboola.com/admin/projects/PROJECT_ID/branch/BRANCH_ID/dashboard. The branch ID must be included in each request using the header X-Branch-Id: <branchId>, otherwise the MCP Server uses production branch as default. This should be managed by the AI client or the environment handling the server connection.
When using HTTP-based transports (Streamable HTTP), you can control which tools are available to clients using HTTP headers. This is useful for restricting AI agent capabilities or enforcing compliance policies.
Filters apply in order: allowed → read-only intersection → disallowed exclusion. Empty headers = no restriction.
Read-only tools are those annotated with readOnlyHint=True. These tools only retrieve information without making any changes to your Keboola project. For the current list of read-only tools, see the TOOLS.md file which is an auto-generated snapshot of the actual tool set.
X-Read-Only-Mode: true
Claude Code / Claude Agent SDK clients that register the server with alwaysLoad: true keep these tools deferred behind tool search instead of loading their definitions up front. The header only changes the tools/list metadata — it does not hide or authorize tools. Empty header or unknown tool names = no change.
For detailed documentation, see developers.keboola.com/integrate/mcp/#tool-authorization-and-access-control.
Row- and column-level policies are Keboola Metastore objects (rls-policy, cls-policy), authored with
kbagent rls / kbagent cls. This server neither reads nor applies them. In a project that has the
row-level-security feature it creates its workspace (the mcp-workspace-<hex> configuration of the
keboola.mcp-server-tool component) with the Connection login type governed. A governed workspace has no
credentials: only the Query Service can read it, and the Query Service filters every query_data result by the
policies of the project. There is no rewriting in this server and no fallback: what the Query Service refuses,
query_data returns as an error.
governed: a stack that does not refuses the create, and then every tool that needs the workspace fails (there is
no fallback to an ordinary workspace). BigQuery projects keep an ordinary, unfiltered workspace. An older ordinary
MCP workspace is not deleted: it is skipped as soon as the feature is on, and workspace_schema or an
X-Workspace-Id pin can still select it.rls-policy applies to (a
"*" rule opens a table to every identified reader); a cls-policy alone grants no rows. A statement that reads
no table (SELECT 1) runs. A refusal reaches the agent as Row-level security does not allow this query.kbc_at_ / kbc_pat_, sent with X-KBC-ProjectId). A session that has only a legacy Storage token, or that
this server cannot map to a user (for example Kai), has no verified identity and reads nothing from a governed
table. Group rules never match (an OAuth login carries no groups).KID:<stack id>:project-<project id>:workspace-<workspace id>
(a workspace of the default branch; a branch workspace also has branch-<branch id> before project). The stack
id is the one the Query Service is configured with (QUERY_RLS_STACK_ID, for example dev-keboola-aws-eu-west-1),
the workspace id is in the get_project_info output, and
kbagent rls bind --project P --workspace-id WS --rls-policy ID --stack-id S writes the binding. A binding only
narrows, applies to the next query, and does not follow the session to another workspace: a branch session, or a
workspace that is recreated, has a new KID and starts again with every policy.WORKSPACE_ID when no
separate workspace is provisioned for it; the app queries with its own token, has no verified identity, and reads
nothing from governed tables. The metadata tools (get_tables, get_buckets, search) are not filtered by the
policies: they can list tables that a governed workspace refuses to read.Run the MCP server on your own machine for full control and easy development. Choose this when you want to customize tools, debug locally, or iterate quickly. You’ll install the server, authenticate (a one-time browser login — no token to paste), and start it. This approach offers maximum flexibility (custom tools, local logging, offline iteration) but requires manual setup and you manage updates and secrets yourself.
The server supports multiple transport options, which can be selected by providing the --transport <transport> argument when starting the server:
stdio - Default when --transport is not specified. Standard input/output, typically used for local deployment with a single client.streamable-http - Runs the server remotely over HTTP with a bidirectional streaming channel, allowing the client and server to continuously exchange messages. Connect via /mcp (e.g., http://localhost:8000/mcp).http-compat - An alias for streamable-http, kept for backwards compatibility.To work with your Keboola project the server needs two things: your Keboola Region (KBC_STORAGE_API_URL) and a way to authenticate. The recommended way is a one-time browser login — you never create, copy, or paste a token. Optionally set KBC_BRANCH_ID to work inside a development branch.
Some of the variables are not taken from the request headers:
KBC_STORAGE_API_URL: a server that was started with its own Storage API URL (the --api-url parameter or the KBC_STORAGE_API_URL environment variable) only serves that one Keboola stack. An X-Storage-Api-Url header asking for a different host is ignored (a warning is logged) — the server keeps its own URL for the request. Start the server without a Storage API URL of its own if you want each request to choose its stack.KBC_KUBERNETES_TOKEN_PATH (deployed servers only, see docs/kubernetes-sa-auth.md): read from the environment only, never from a header.KBC_WORKSPACE_ID / KBC_WORKSPACE_SCHEMA: same idea as the Storage API URL above — a server started with its own workspace pin (via either variable, or --workspace-id) keeps that pin for every request; an X-Workspace-Id or X-Workspace-Schema header asking for a different workspace is ignored (a warning is logged). A server with no pin of its own (the shared multi-user case) keeps taking the pin from the request, per-request, as described below.Sign in once with your browser; the server stores the session and refreshes it automatically, so there are no tokens to manage:
uvx keboola_mcp_server login --api-url https://connection.YOUR_REGION.keboola.com
This opens your browser to sign in to Keboola, then saves the stack-wide session to ~/.keboola/mcp/credentials.json (readable only by you, one entry per stack). Afterwards, start the server with only KBC_STORAGE_API_URL set — no token required. Which project(s) to work on is chosen afterwards, in the conversation (get_accessible_projects / set_project_scope), not during login.
When you start the server over stdio in an interactive terminal with no stored session, it runs this browser login automatically on first start. MCP clients (Claude, Cursor, …) launch the server in the background where a browser can't open, so run login once yourself first.
You can also start the server with only KBC_STORAGE_API_URL and no credentials at all. It comes up in bootstrap mode: tools that need Keboola access explain how to get a credential, and one tool works without one — create_project. It creates a new Keboola project, signs the session in to it, and returns a confirmation URL. Opening that URL in a browser and signing in makes the project permanently yours; until then it is temporary and Keboola may reclaim it, and once you confirm, the session the tool created is revoked and you continue with your own login.
This needs a stack with agent provisioning enabled; elsewhere the tool reports that it is not available.
The same thing is possible without running a server at all, on a remotely hosted MCP server whose
operator has enabled it (KBC_ALLOW_ANONYMOUS_PROVISIONING): such a deployment also serves
https://mcp.<stack>/mcp-anonymous, which accepts no credentials. Point your client there with no
authentication, call create_project, and keep working in the project that call created — the server
holds its credentials for you and the tool hands back an opaque scope_token to resend on later
calls. It is a separate URL because the ordinary /mcp endpoint has to keep refusing unauthenticated
requests: that refusal is how MCP clients know to start the OAuth login. Once you claim the project,
switch to /mcp and sign in with the account that now owns it.
For containers or CI where a browser login isn't possible, provide a Keboola access or personal access token directly — set KBC_STORAGE_TOKEN (env var) or send the X-StorageAPI-Token header — together with KBC_PROJECT_ID (or the X-KBC-ProjectId header) to select the project. On HTTP transports these can be supplied per request as headers, so each request carries its own credentials.
Pins queries to one specific, already-existing workspace by its ID instead of the schema-based lookup above, and takes precedence over KBC_WORKSPACE_SCHEMA when both are set. This is the option a Data App / kai-agent caller supplies, as the X-Workspace-Id header, so that Kai embedded in that app queries only through its own workspace.
Set via the KBC_WORKSPACE_ID environment variable, the --workspace-id CLI flag, or (per-request, for multi-user deployments) the X-Workspace-Id header.
Your Keboola Region API URL depends on your deployment region. You can determine your region by looking at the URL in your browser when logged into your Keboola project:
To operate on a specific Keboola development branch, set the branch ID using the KBC_BRANCH_ID parameter. The MCP server scopes its functionality to the specified branch, ensuring all changes remain isolated and do not impact the production branch.
KBC_BRANCH_ID to the numeric ID of your branch (e.g., 123456). You can find the development branch ID in the URL when navigating to the development branch in the UI, for example: https://connection.us-east4.gcp.keboola.com/admin/projects/PROJECT_ID/branch/BRANCH_ID/dashboard.X-Branch-Id: <branchId> or KBC_BRANCH_ID: <branchId>.Make sure you have:
Note: Make sure you have uv installed. The MCP client will use it to automatically download and run the Keboola MCP Server.
Installing 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
For more installation options, see the official uv documentation.
There are four ways to use the Keboola MCP Server, depending on your needs:
In this mode, Claude or Cursor automatically starts the MCP server for you.
uvx keboola_mcp_server login --api-url https://connection.YOUR_REGION.keboola.com
KBC_STORAGE_API_URL is needed.{
"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"
}
}
}
}
Config file locations:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json{
"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"
}
}
}
}
Note: Use short, descriptive names for MCP servers. Since the full tool name includes the server name and must stay under ~60 characters, longer names may be filtered out in Cursor and will not be displayed to the Agent.
When running the MCP server from Windows Subsystem for Linux with Cursor AI, use this configuration:
{
"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>",
"'"
]
}
}
}
For developers working on the MCP server code itself:
{
"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"
}
}
}
}
You can run the server manually in a terminal for testing or debugging:
# 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
Note: This mode is primarily for debugging or testing. For normal use with Claude or Cursor, you do not need to manually run the server.
Note: The server will use the Streamable HTTP transport and listen on
localhost:8000for incoming connections at/mcp. You can use--portand--hostparameters to make it listen elsewhere.
A container can't open a browser, so authenticate with a token (see Authenticating without a browser): set KBC_STORAGE_TOKEN to a Keboola access/personal access token and KBC_PROJECT_ID to the target project. (Over HTTP you can instead pass X-StorageAPI-Token / X-KBC-ProjectId headers per request and omit these.)
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
Note: The server will use the Streamable HTTP transport and listen on
localhost:8000for incoming connections at/mcp. You can change-pto map the container's port somewhere else.
Once your MCP client (Claude/Cursor) is configured and running, you can start querying your Keboola data:
You can start with a simple query to confirm everything is working:
What buckets and tables are in my Keboola project?
Data Exploration:
Data Analysis:
Data Pipelines:
Note: Your AI agents will automatically adjust to new tools.
For a complete list of available tools with detailed descriptions, parameters, and usage examples, see TOOLS.md.
Basic setup:
uv sync --extra dev
With the basic setup, you can use uv run tox to run tests and check code style.
Recommended setup:
uv sync --extra dev --extra tests --extra integtests --extra codestyle
With the recommended setup, packages for testing and code style checking will be installed which allows IDEs like VsCode or Cursor to check the code or run tests during development.
To run integration tests locally, use uv run tox -e integtests.
NOTE: You will need to set the following environment variables:
INTEGTEST_POOL_STORAGE_API_URLINTEGTEST_STORAGE_TOKENSINTEGTEST_STORAGE_TOKEN_STORAGE_BRANCHESIn order to get these values, you need dedicated Keboola projects for integration tests.
Each test session creates its own read-only workspace, so no workspace schema needs to be
configured. See integtests/README.md for detailed setup instructions and design documentation.
uv.lockUpdate the uv.lock file if you have added or removed dependencies. Also consider updating the lock with newer dependency
versions when creating a release (uv lock --upgrade).
When you make changes to any tool descriptions (docstrings in tool functions), you must regenerate the TOOLS.md documentation file to reflect these changes:
uv run python -m src.keboola_mcp_server.generate_tool_docs
We do not cut a release for every merged PR. Work lands on the trunk (main)
continuously, and we release periodically once changes have been re-tested together —
this avoids breaking working setups for users.
A release is made by pushing one or two git tags:
vX.Y.Z — the MCP server release (always)agent-vX.Y.Z — the In Platform Agent release (only when the agent is being released too)Either tag triggers release.yml CI, which builds and publishes the Docker image. KaiBench
runs only on production vX.Y.Z tags (not agent-vX.Y.Z, and not -dev. prereleases). Use
the release-notes skill — it prepares the release notes and draft PR and walks through
tagging both vX.Y.Z and agent-vX.Y.Z.
⭐ The primary way to get help, report bugs, or request features is by opening an issue on GitHub. ⭐
The development team actively monitors issues and will respond as quickly as possible. For general information about Keboola, please use the resources below.
Model Context Protocol (MCP) Server for the Keboola Platform
{ "mcpServers": { "keboola-mcp-server": { "url": "https://mcp.us-east4.gcp.keboola.com/mcp", "headers": {} } }}Herramientas
Aún no hay lista de herramientas. Los servidores remotos la reciben tras la primera comprobación de estado.
Preguntas frecuentes
Copia en esta página la configuración http para Cursor, Claude Desktop, Claude Code o VS Code. Usa la instalación del publicador, no un proxy de PlugMCP.
Este registro no indica ninguna variable de entorno obligatoria.
Se accede a Keboola por HTTP.
Última comprobación: 2026-11-14. Model Context Protocol (MCP) Server for the Keboola Platform