Keboola MCP server for AI agents

Keboola MCP Server acts as a bridge between your Keboola project and modern AI tools, allowing AI agents and assistants to access your data, run transformations, execute SQL queries, and trigger jobs without requiring custom integration code. This server makes your Keboola resources available as callable tools for AI assistants like Claude, Cursor, CrewAI, and more.

Installation Prerequisites

Before setting up the Keboola MCP Server, ensure you have:

Python 3.10 or higher
Access to a Keboola project with admin rights
Your preferred MCP client (Claude, Cursor, etc.)
The uv package installer

Installing uv

macOS/Linux:

brew install uv

Windows:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Required Keboola Information

You'll need three key pieces of information:

KBC_STORAGE_TOKEN: Your authentication token for Keboola
- For full access, use a Master Token
- For limited access, use a custom storage token
KBC_WORKSPACE_SCHEMA: Required only if using a custom storage token
- With Master Token, a workspace is created automatically
- With custom token, you need to create a workspace manually
Keboola Region: Your API URL depends on your deployment region
- 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

Setup Options

Option 1: Using the Remote MCP Server (Easiest)

The simplest way to connect is using Keboola's hosted Remote MCP Server:

Go to your Keboola Project Settings → MCP Server tab
Copy the server URL (looks like https://mcp.<YOUR_REGION>.keboola.com/sse)
Configure your AI assistant with this URL
Authenticate with your Keboola account when prompted

Option 2: Integrated Mode (Recommended for Local Setup)

Let Claude or Cursor automatically start the MCP server for you:

Claude Desktop Configuration

Go to Claude → Settings → Developer → Edit Config
Add the following configuration:

{
  "mcpServers": {
    "keboola": {
      "command": "uvx",
      "args": ["keboola_mcp_server"],
      "env": {
        "KBC_STORAGE_API_URL": "https://connection.YOUR_REGION.keboola.com",
        "KBC_STORAGE_TOKEN": "your_keboola_storage_token",
        "KBC_WORKSPACE_SCHEMA": "your_workspace_schema"
      }
    }
  }
}

Restart Claude desktop

Cursor Configuration

Go to Settings → MCP
Click "+ Add new global MCP Server"
Use the same configuration as shown above

Option 3: Manual CLI Mode (For Testing)

Run the server manually in a terminal:

# 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

uvx keboola_mcp_server --transport sse

Option 4: Using 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" \
  keboola/mcp-server:latest \
  --transport sse \
  --host 0.0.0.0

Using the MCP Server

Once configured, you can interact with your Keboola project through your AI assistant:

Verify Your Setup

Start with a simple query:

What buckets and tables are in my Keboola project?

Example Queries

Data Exploration:

"What tables contain customer information?"
"Run a query to find the top 10 customers by revenue"

Data Analysis:

"Analyze my sales data by region for the last quarter"
"Find correlations between customer age and purchase frequency"

Data Pipelines:

"Create a SQL transformation that joins customer and order tables"
"Start the data extraction job for my Salesforce component"

Supported Tools

The MCP Server provides various tools that your AI assistants can use:

Project Tools

get_project_info: Gets structured information about your Keboola project

Storage Tools

list_buckets: Lists all storage buckets in your project
get_bucket: Retrieves information about a specific bucket
list_tables: Returns all tables within a specific bucket
get_table: Provides detailed information for a specific table
update_bucket_description: Updates a bucket's description
update_column_description: Updates a column's description
update_table_description: Updates a table's description

SQL Tools

query_table: Executes custom SQL queries against your data
get_sql_dialect: Identifies whether your workspace uses Snowflake or BigQuery SQL dialect

Component Tools

create_config: Creates a component configuration
create_sql_transformation: Creates an SQL transformation
list_configs: Retrieves component configurations
list_transformations: Retrieves transformation configurations
And many more component management tools

Job Tools

retrieve_jobs: Lists and filters jobs
get_job_detail: Returns details about a specific job
start_job: Triggers a component or transformation job

Flow Tools

create_flow: Creates a new flow configuration
get_flow: Gets information about a specific flow
list_flows: Retrieves flow configurations
update_flow: Updates an existing flow configuration

Documentation Tools

docs_query: Searches Keboola documentation based on natural language queries

Troubleshooting

Common Issues

Issue	Solution
Authentication Errors	Verify `KBC_STORAGE_TOKEN` is valid
Workspace Issues	Confirm `KBC_WORKSPACE_SCHEMA` is correct
Connection Timeout	Check network connectivity

Compatible Clients

The MCP Server works with various clients:

Claude (Desktop & Web)
Cursor
Windsurf, Zed, Replit
Codeium, Sourcegraph
Other custom MCP clients

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "keboola" '{"command":"uvx","args":["keboola_mcp_server"],"env":{"KBC_STORAGE_API_URL":"https://connection.YOUR_REGION.keboola.com","KBC_STORAGE_TOKEN":"your_keboola_storage_token","KBC_WORKSPACE_SCHEMA":"your_workspace_schema"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "keboola": {
            "command": "uvx",
            "args": [
                "keboola_mcp_server"
            ],
            "env": {
                "KBC_STORAGE_API_URL": "https://connection.YOUR_REGION.keboola.com",
                "KBC_STORAGE_TOKEN": "your_keboola_storage_token",
                "KBC_WORKSPACE_SCHEMA": "your_workspace_schema"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

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

2. Add this to your configuration file:

{
    "mcpServers": {
        "keboola": {
            "command": "uvx",
            "args": [
                "keboola_mcp_server"
            ],
            "env": {
                "KBC_STORAGE_API_URL": "https://connection.YOUR_REGION.keboola.com",
                "KBC_STORAGE_TOKEN": "your_keboola_storage_token",
                "KBC_WORKSPACE_SCHEMA": "your_workspace_schema"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect