Keboola Explorer MCP server

Keboola MCP Server enables AI agents and tools to connect directly to your Keboola project, giving them access to data, transformations, SQL queries, and job triggers without additional integration code. It bridges your Keboola resources with modern AI assistants like Claude, Cursor, CrewAI, and more.

Prerequisites

Before getting started, you'll need:

• 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:

# 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 additional installation options, visit the official uv documentation.

Required Information

Before setting up the MCP server, gather these three essential pieces of information:

1. KBC_STORAGE_TOKEN - Your authentication token for Keboola

   • Create and manage tokens via the Keboola documentation
   • Note: Use a custom storage token for limited access or a master token for full project access

2. KBC_WORKSPACE_SCHEMA - Identifies your workspace in Keboola (required for SQL queries)

   • Follow the Keboola workspace guide to get this value
   • Important: Enable "Grant read-only access to all Project data" when creating the workspace

3. Keboola Region URL - Depends on your deployment region:

BigQuery-Specific Setup

If your Keboola project uses BigQuery:

1. Go to your Keboola BigQuery workspace and display its credentials (click Connect button)
2. Download the credentials JSON file to your local disk
3. Set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the full path of this file
4. Note: In BigQuery, the KBC_WORKSPACE_SCHEMA is called "Dataset Name" in the workspace

Setting Up Keboola MCP Server

You can run the Keboola MCP Server in four different ways:

Option A: Integrated Mode (Recommended)

Claude or Cursor automatically starts the MCP server for you - no manual commands needed.

Claude Desktop Configuration

1. Go to Claude (top left) → Settings → Developer → Edit Config
2. Add the following configuration:
3. Restart Claude desktop

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

For BigQuery users, add this line to the "env" section:

"GOOGLE_APPLICATION_CREDENTIALS": "/full/path/to/credentials.json"

Config file locations:

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

Cursor Configuration

1. Go to Settings → MCP
2. Click "+ Add new global MCP Server"
3. Configure with these settings:

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

For BigQuery users, add this line to the "env" section:

"GOOGLE_APPLICATION_CREDENTIALS": "/full/path/to/credentials.json"

Cursor Configuration for Windows WSL

When using Windows Subsystem for Linux with Cursor AI:

{
  "mcpServers": {
    "keboola": {
      "command": "wsl.exe",
      "args": [
        "bash",
        "-c",
        "'source /wsl_path/to/keboola-mcp-server/.env",
        "&&",
        "/wsl_path/to/keboola-mcp-server/.venv/bin/python -m keboola_mcp_server.cli --transport stdio'"
      ]
    }
  }
}

Create a .env file at /wsl_path/to/keboola-mcp-server/.env containing:

export KBC_STORAGE_TOKEN="your_keboola_storage_token"
export KBC_WORKSPACE_SCHEMA="your_workspace_schema"

Option B: Local Development Mode

For developing with the MCP server code:

{
  "mcpServers": {
    "keboola": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": [
        "-m", "keboola_mcp_server.cli",
        "--transport", "stdio",
        "--api-url", "https://connection.YOUR_REGION.keboola.com"
      ],
      "env": {
        "KBC_STORAGE_TOKEN": "your_keboola_storage_token",
        "KBC_WORKSPACE_SCHEMA": "your_workspace_schema"
      }
    }
  }
}

For BigQuery users, add the GOOGLE_APPLICATION_CREDENTIALS line to the "env" section.

Option C: Manual CLI Mode (For Testing)

Run the server in a terminal for testing:

# Set environment variables
export KBC_STORAGE_TOKEN=your_keboola_storage_token
export KBC_WORKSPACE_SCHEMA=your_workspace_schema
# For BigQuery users
# export GOOGLE_APPLICATION_CREDENTIALS=/full/path/to/credentials.json

# Run with uvx (no installation needed)
uvx keboola_mcp_server --api-url https://connection.YOUR_REGION.keboola.com

# OR, if developing locally
python -m keboola_mcp_server.cli --api-url https://connection.YOUR_REGION.keboola.com

Option D: Using Docker

docker pull keboola/mcp-server:latest

# For Snowflake users
docker run -it \
  -e KBC_STORAGE_TOKEN="YOUR_KEBOOLA_STORAGE_TOKEN" \
  -e KBC_WORKSPACE_SCHEMA="YOUR_WORKSPACE_SCHEMA" \
  keboola/mcp-server:latest \
  --api-url https://connection.YOUR_REGION.keboola.com

# For BigQuery users (add credentials volume mount)
# docker run -it \
#   -e KBC_STORAGE_TOKEN="YOUR_KEBOOLA_STORAGE_TOKEN" \
#   -e KBC_WORKSPACE_SCHEMA="YOUR_WORKSPACE_SCHEMA" \
#   -e GOOGLE_APPLICATION_CREDENTIALS="/creds/credentials.json" \
#   -v /local/path/to/credentials.json:/creds/credentials.json \
#   keboola/mcp-server:latest \
#   --api-url https://connection.YOUR_REGION.keboola.com

Using the MCP Server

Once configured, you can query your Keboola data through your MCP client.

Verify Your Setup

Start with a simple verification 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 access to these capabilities (organized by category):

Storage Tools

• retrieve_buckets - Lists all storage buckets in your project
• get_bucket_detail - Gets detailed information about a specific bucket
• retrieve_bucket_tables - Lists all tables within a specific bucket
• get_table_detail - Provides detailed information for a specific table
• update_bucket_description - Updates a bucket's description
• update_column_description - Updates a column 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

Component Tools

• create_component_root_configuration - Creates a component configuration
• create_component_row_configuration - Creates a component configuration row
• create_sql_transformation - Creates an SQL transformation with custom queries
• find_component_id - Finds component IDs matching a query
• get_component - Gets information about a specific component
• get_component_configuration - Gets information about a specific configuration
• get_component_configuration_examples - Retrieves sample configurations
• retrieve_component_configurations - Lists component configurations
• retrieve_transformations - Lists transformation configurations
• update_component_root_configuration - Updates a component configuration
• update_component_row_configuration - Updates a configuration row
• update_sql_transformation_configuration - Updates an SQL transformation

Job Tools

• retrieve_jobs - Lists and filters jobs
• get_job_detail - Gets detailed information about a specific job
• start_job - Triggers a component or transformation job

Documentation Tools

• docs_query - Searches Keboola documentation based on natural language queries

Compatibility

MCP Client Support

Troubleshooting

Common Issues

How to add this MCP server to 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 > MCP and click "Add new global MCP server".

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

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

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 explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.