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. - Quick Start - Local Setup With the AI Agent and MCP Server, you can: - Storage: Query tables directly and manage table or bucket description
Add this skill
npx mdskills install keboola/keboola-mcp-serverComprehensive MCP server connecting AI agents to Keboola data platform with rich tooling and multiple transport options
1[](https://deepwiki.com/keboola/mcp-server)23# Keboola MCP Server45> 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.67## Overview89Keboola 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.1011- [Quick Start](#-quick-start-remote-mcp-server-easiest-way)12- [Local Setup](#local-mcp-server-setup-custom-or-dev-way)1314## Features1516With the AI Agent and MCP Server, you can:1718- **Storage**: Query tables directly and manage table or bucket descriptions19- **Components**: Create, List and inspect extractors, writers, data apps, and transformation configurations20- **SQL**: Create SQL transformations with natural language21- **Jobs**: Run components and transformations, and retrieve job execution details22- **Flows**: Build and manage workflow pipelines using Conditional Flows and Orchestrator Flows.23- **Data Apps**: Create, deploy and manage Keboola Streamlit Data Apps displaying your queries over storage data.24- **Metadata**: Search, read, and update project documentation and object metadata using natural language25- **Dev Branches**: Work safely in development branches outside of production, where all operations are scoped to the selected branch.2627---2829## 🚀 Quick Start: Remote MCP Server (Easiest Way)3031<div class="alert alert-warning" role="alert">32<strong>⚠️ SSE Transport Decommissioning:</strong> The SSE transport is deprecated and will be removed from the Keboola MCP Server on 2026-Mar-31. Please migrate to the Streamable HTTP transport and use the <code>/mcp</code> endpoints instead of <code>/sse</code>.33</div>3435The 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.3637### What is the Remote MCP Server?3839Our 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.4041### How to Connect42431. **Get your remote server URL**: Navigate to your Keboola Project Settings → `MCP Server` tab442. **Copy the server URL**: It will look like `https://mcp.<YOUR_REGION>.keboola.com/mcp`453. **Configure your AI assistant**: Paste the URL into your AI assistant's MCP settings464. **Authenticate**: You'll be prompted to authenticate with your Keboola account and select your project4748### Supported Clients4950- **[Cursor](https://cursor.com)**: Use the "Install In Cursor" button in your project's MCP Server settings or click51 this button52 [](cursor://anysphere.cursor-deeplink/mcp/install?name=keboola&config=eyJ1cmwiOiJodHRwczovL21jcC51cy1lYXN0NC5nY3Aua2Vib29sYS5jb20vbWNwIn0%3D)53- **[Claude Desktop](https://claude.ai)**: Add the integration via Settings → Integrations54- **[Claude Code](https://www.anthropic.com/)**: Install using `claude mcp add --transport http keboola <URL>` (see below for details)55- **[Windsurf](https://windsurf.ai)**: Configure with the remote server URL56- **[Make](https://make.com)**: Configure with the remote server URL57- **Other MCP clients**: Configure with the remote server URL5859#### Claude Code Setup6061Claude 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.6263**Installation:**6465Run the following command in your terminal, replacing `<YOUR_REGION>` with your Keboola region:6667```bash68claude mcp add --transport http keboola https://mcp.<YOUR_REGION>.keboola.com/mcp69```7071**Region-specific commands:**7273| Region | Installation Command |74|--------|----------------------|75| US Virginia AWS | `claude mcp add --transport http keboola https://mcp.keboola.com/mcp` |76| US Virginia GCP | `claude mcp add --transport http keboola https://mcp.us-east4.gcp.keboola.com/mcp` |77| EU Frankfurt AWS | `claude mcp add --transport http keboola https://mcp.eu-central-1.keboola.com/mcp` |78| EU Ireland Azure | `claude mcp add --transport http keboola https://mcp.north-europe.azure.keboola.com/mcp` |79| EU Frankfurt GCP | `claude mcp add --transport http keboola https://mcp.europe-west3.gcp.keboola.com/mcp` |8081**Usage:**8283Once 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.8485**Authentication:**8687When you first use the Keboola MCP Server in Claude Code, a browser window will open prompting you to:881. Log in with your Keboola account892. Select the project you want to connect to903. Authorize the connection9192After authentication, you can start using Keboola tools directly from Claude Code.9394For detailed setup instructions and region-specific URLs, see our [Remote Server Setup documentation](https://help.keboola.com/ai/mcp-server/#remote-server-setup).9596### Using Development Branches97You can work safely in [Keboola development branches](https://help.keboola.com/components/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.9899### Tool Authorization and Access Control100101When 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.102103#### Authorization Headers104105| Header | Description | Example |106|--------|-------------|---------|107| `X-Allowed-Tools` | Comma-separated list of allowed tools | `get_configs,get_buckets,query_data` |108| `X-Disallowed-Tools` | Comma-separated list of tools to exclude | `create_config,run_job` |109| `X-Read-Only-Mode` | Restrict to read-only tools only | `true`, `1`, or `yes` |110111#### Filter Behavior112113Filters apply in order: allowed → read-only intersection → disallowed exclusion. Empty headers = no restriction.114115#### Read-Only Tools116117Read-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](TOOLS.md) file which is an auto-generated snapshot of the actual tool set.118119#### Example: Read-Only Access120121```122X-Read-Only-Mode: true123```124125For detailed documentation, see [developers.keboola.com/integrate/mcp/#tool-authorization-and-access-control](https://developers.keboola.com/integrate/mcp/#tool-authorization-and-access-control).126127---128129## Local MCP Server Setup (Custom or Dev Way)130131Run 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 clone the repo, set Keboola credentials via environment variables or headers depending on the server transport, install dependencies, and start the server. This approach offers maximum flexibility (custom tools, local logging, offline iteration) but requires manual setup and you manage updates and secrets yourself.132133The server supports multiple **transport** options, which can be selected by providing the `--transport <transport>` argument when starting the server:134- `stdio` - Default when `--transport` is not specified. Standard input/output, typically used for local deployment with a single client.135- `streamable-http` - Runs the server remotely over HTTP with a bidirectional streaming channel, allowing the client and server to continuously exchange messages. Connect via <url>/mcp (e.g., http://localhost:8000/mcp).136- `sse` - **Deprecated (will be removed on 2026-Mar-31)**, use `streamable-http` instead. Runs the server remotely using Server-Sent Events (SSE) for one-way event streaming from server to client. Connect via <url>/sse (e.g., http://localhost:8000/sse).137- `http-compat` - A custom transport supporting both `SSE` and `streamable-http`. It is currently used on Keboola remote servers but will be replaced by `streamable-http` only when SSE is removed.138139For client–server communication, Keboola credentials must be provided to enable working with your project in your Keboola Region. The following are required: `KBC_STORAGE_TOKEN`, `KBC_STORAGE_API_URL`, `KBC_WORKSPACE_SCHEMA` and optionally `KBC_BRANCH_ID`. You can provide these in two ways:140- For personal use (mainly with stdio transport): set the environment variables before starting the server. All requests will reuse these predefined credentials.141- For multi-user use: include the variables in the request headers so that each request uses the credentials provided with it.142143144### KBC_STORAGE_TOKEN145146This is your authentication token for Keboola:147148For instructions on how to create and manage Storage API tokens, refer to the [official Keboola documentation](https://help.keboola.com/management/project/tokens/).149150**Note**: If you want the MCP server to have limited access, use custom storage token, if you want the MCP to access everything in your project, use the master token.151152### KBC_WORKSPACE_SCHEMA153154This identifies your workspace in Keboola and is used for SQL queries. However, this is **only required if you're using a custom storage token** instead of the Master Token:155156- If using [Master Token](https://help.keboola.com/management/project/tokens/#master-tokens): The workspace is created automatically behind the scenes157- If using [custom storage token](https://help.keboola.com/management/project/tokens/#limited-tokens): Follow this [Keboola guide](https://help.keboola.com/tutorial/manipulate/workspace/) to get your KBC_WORKSPACE_SCHEMA158159**Note**: When creating a workspace manually, check Grant read-only access to all Project data option160161**Note**: KBC_WORKSPACE_SCHEMA is called Dataset Name in BigQuery workspaces, you simply click connect and copy the Dataset Name162163### KBC_STORAGE_API_URL (Keboola Region)164165Your 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:166167| Region | API URL |168|--------|---------|169| AWS North America | `https://connection.keboola.com` |170| AWS Europe | `https://connection.eu-central-1.keboola.com` |171| Google Cloud EU | `https://connection.europe-west3.gcp.keboola.com` |172| Google Cloud US | `https://connection.us-east4.gcp.keboola.com` |173| Azure EU | `https://connection.north-europe.azure.keboola.com` |174175### KBC_BRANCH_ID (Optional)176177To operate on a specific [Keboola development branch](https://help.keboola.com/components/branches/), 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.178179- If not provided, the server uses the production branch by default.180- For development work, set `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`.181- On remote transports, you can override per-request with the HTTP header `X-Branch-Id: <branchId>` or `KBC_BRANCH_ID: <branchId>`.182183184### Installation185186Make sure you have:187188- [ ] Python 3.10+ installed189- [ ] Access to a Keboola project with admin rights190- [ ] Your preferred MCP client (Claude, Cursor, etc.)191192**Note**: Make sure you have `uv` installed. The MCP client will use it to automatically download and run the Keboola MCP Server.193**Installing uv**:194195*macOS/Linux*:196197```bash198#if homebrew is not installed on your machine use:199# /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"200201# Install using Homebrew202brew install uv203```204205*Windows*:206207```powershell208# Using the installer script209powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"210211# Or using pip212pip install uv213214# Or using winget215winget install --id=astral-sh.uv -e216```217218For more installation options, see the [official uv documentation](https://docs.astral.sh/uv/getting-started/installation/).219220221### Running Keboola MCP Server222223There are four ways to use the Keboola MCP Server, depending on your needs:224225### Option A: Integrated Mode (Recommended)226227In this mode, Claude or Cursor automatically starts the MCP server for you. **You do not need to run any commands in your terminal**.2282291. Configure your MCP client (Claude/Cursor) with the appropriate settings2302. The client will automatically launch the MCP server when needed231232#### Claude Desktop Configuration2332341. Go to Claude (top left corner of your screen) -> Settings → Developer → Edit Config (if you don't see the claude_desktop_config.json, create it)2352. Add the following configuration:2363. Restart Claude desktop for changes to take effect237238```json239{240 "mcpServers": {241 "keboola": {242 "command": "uvx",243 "args": ["keboola_mcp_server --transport <transport>"],244 "env": {245 "KBC_STORAGE_API_URL": "https://connection.YOUR_REGION.keboola.com",246 "KBC_STORAGE_TOKEN": "your_keboola_storage_token",247 "KBC_WORKSPACE_SCHEMA": "your_workspace_schema",248 "KBC_BRANCH_ID": "your_branch_id_optional"249 }250 }251 }252}253```254255Config file locations:256257- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`258- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`259260#### Cursor Configuration2612621. Go to Settings → MCP2632. Click "+ Add new global MCP Server"2643. Configure with these settings:265266```json267{268 "mcpServers": {269 "keboola": {270 "command": "uvx",271 "args": ["keboola_mcp_server --transport <transport>"],272 "env": {273 "KBC_STORAGE_API_URL": "https://connection.YOUR_REGION.keboola.com",274 "KBC_STORAGE_TOKEN": "your_keboola_storage_token",275 "KBC_WORKSPACE_SCHEMA": "your_workspace_schema",276 "KBC_BRANCH_ID": "your_branch_id_optional"277 }278 }279 }280}281```282283**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.284285286#### Cursor Configuration for Windows WSL287288When running the MCP server from Windows Subsystem for Linux with Cursor AI, use this configuration:289290```json291{292 "mcpServers": {293 "keboola":{294 "command": "wsl.exe",295 "args": [296 "bash",297 "-c '",298 "export KBC_STORAGE_API_URL=https://connection.YOUR_REGION.keboola.com &&",299 "export KBC_STORAGE_TOKEN=your_keboola_storage_token &&",300 "export KBC_WORKSPACE_SCHEMA=your_workspace_schema &&",301 "export KBC_BRANCH_ID=your_branch_id_optional &&",302 "/snap/bin/uvx keboola_mcp_server --transport <transport>",303 "'"304 ]305 }306 }307}308```309310### Option B: Local Development Mode311312For developers working on the MCP server code itself:3133141. Clone the repository and set up a local environment3152. Configure Claude/Cursor to use your local Python path:316317```json318{319 "mcpServers": {320 "keboola": {321 "command": "/absolute/path/to/.venv/bin/python",322 "args": [323 "-m",324 "keboola_mcp_server --transport <transport>"325 ],326 "env": {327 "KBC_STORAGE_API_URL": "https://connection.YOUR_REGION.keboola.com",328 "KBC_STORAGE_TOKEN": "your_keboola_storage_token",329 "KBC_WORKSPACE_SCHEMA": "your_workspace_schema",330 "KBC_BRANCH_ID": "your_branch_id_optional"331 }332 }333 }334}335```336337### Option C: Manual CLI Mode (For Testing Only)338339You can run the server manually in a terminal for testing or debugging:340341```bash342# Set environment variables343export KBC_STORAGE_API_URL=https://connection.YOUR_REGION.keboola.com344export KBC_STORAGE_TOKEN=your_keboola_storage_token345export KBC_WORKSPACE_SCHEMA=your_workspace_schema346export KBC_BRANCH_ID=your_branch_id_optional347348uvx keboola_mcp_server --transport streamable-http349```350351> **Note**: This mode is primarily for debugging or testing. For normal use with Claude or Cursor,352> you do not need to manually run the server.353354> **Note**: The server will use the Streamable HTTP transport and listen on `localhost:8000` for incoming connections at `/mcp`.355> You can use `--port` and `--host` parameters to make it listen elsewhere.356357### Option D: Using Docker358359```shell360docker pull keboola/mcp-server:latest361362docker run \363 --name keboola_mcp_server \364 --rm \365 -it \366 -p 127.0.0.1:8000:8000 \367 -e KBC_STORAGE_API_URL="https://connection.YOUR_REGION.keboola.com" \368 -e KBC_STORAGE_TOKEN="YOUR_KEBOOLA_STORAGE_TOKEN" \369 -e KBC_WORKSPACE_SCHEMA="YOUR_WORKSPACE_SCHEMA" \370 -e KBC_BRANCH_ID="YOUR_BRANCH_ID_OPTIONAL" \371 keboola/mcp-server:latest \372 --transport streamable-http \373 --host 0.0.0.0374```375376> **Note**: The server will use the Streamable HTTP transport and listen on `localhost:8000` for incoming connections at `/mcp`.377> You can change `-p` to map the container's port somewhere else.378379### Do I Need to Start the Server Myself?380381| Scenario | Need to Run Manually? | Use This Setup |382|----------|----------------------|----------------|383| Using Claude/Cursor | No | Configure MCP in app settings |384| Developing MCP locally | No (Claude starts it) | Point config to python path |385| Testing CLI manually | Yes | Use terminal to run |386| Using Docker | Yes | Run docker container |387388## Using MCP Server389390Once your MCP client (Claude/Cursor) is configured and running, you can start querying your Keboola data:391392### Verify Your Setup393394You can start with a simple query to confirm everything is working:395396```text397What buckets and tables are in my Keboola project?398```399400### Examples of What You Can Do401402**Data Exploration:**403404- "What tables contain customer information?"405- "Run a query to find the top 10 customers by revenue"406407**Data Analysis:**408409- "Analyze my sales data by region for the last quarter"410- "Find correlations between customer age and purchase frequency"411412**Data Pipelines:**413414- "Create a SQL transformation that joins customer and order tables"415- "Start the data extraction job for my Salesforce component"416417## Compatibility418419### MCP Client Support420421| **MCP Client** | **Support Status** | **Connection Method** |422|----------------|-------------------|----------------------|423| Claude (Desktop & Web) | ✅ supported | stdio |424| Cursor | ✅ supported | stdio |425| Windsurf, Zed, Replit | ✅ Supported | stdio |426| Codeium, Sourcegraph | ✅ Supported | HTTP+SSE |427| Custom MCP Clients | ✅ Supported | HTTP+SSE or stdio |428429## Supported Tools430431**Note:** Your AI agents will automatically adjust to new tools.432433For a complete list of available tools with detailed descriptions, parameters, and usage examples, see [TOOLS.md](TOOLS.md).434435## Troubleshooting436437### Common Issues438439| Issue | Solution |440|-------|----------|441| **Authentication Errors** | Verify `KBC_STORAGE_TOKEN` is valid |442| **Workspace Issues** | Confirm `KBC_WORKSPACE_SCHEMA` is correct |443| **Connection Timeout** | Check network connectivity |444445## Development446447### Installation448449Basic setup:450451```bash452uv sync --extra dev453```454455With the basic setup, you can use `uv run tox` to run tests and check code style.456457Recommended setup:458459```bash460uv sync --extra dev --extra tests --extra integtests --extra codestyle461```462463With the recommended setup, packages for testing and code style checking will be installed which allows IDEs like464VsCode or Cursor to check the code or run tests during development.465466### Integration tests467468To run integration tests locally, use `uv run tox -e integtests`.469NOTE: You will need to set the following environment variables:470471- `INTEGTEST_STORAGE_API_URL`472- `INTEGTEST_STORAGE_TOKEN`473- `INTEGTEST_WORKSPACE_SCHEMA`474475In order to get these values, you need a dedicated Keboola project for integration tests.476477### Updating `uv.lock`478479Update the `uv.lock` file if you have added or removed dependencies. Also consider updating the lock with newer dependency480versions when creating a release (`uv lock --upgrade`).481482### Updating Tool Documentation483484When you make changes to any tool descriptions (docstrings in tool functions), you must regenerate the `TOOLS.md` documentation file to reflect these changes:485486```bash487uv run python -m src.keboola_mcp_server.generate_tool_docs488```489490## Support and Feedback491492**⭐ The primary way to get help, report bugs, or request features is by [opening an issue on GitHub](https://github.com/keboola/mcp-server/issues/new). ⭐**493494The development team actively monitors issues and will respond as quickly as possible. For general information about Keboola, please use the resources below.495496## Resources497498- [User Documentation](https://help.keboola.com/)499- [Developer Documentation](https://developers.keboola.com/)500- [Keboola Platform](https://www.keboola.com)501- [Issue Tracker](https://github.com/keboola/mcp-server/issues/new) ← **Primary contact method for MCP Server**502503## Connect504505- [LinkedIn](https://www.linkedin.com/company/keboola)506- [Twitter](https://x.com/keboola)507- [Changelog](https://changelog.keboola.com/)508509510[//]: # (mcp-name: com.keboola/mcp -- keep this line for registry.modelcontextprotocol.io)511
Full transparency — inspect the skill content before installing.