home / mcp / keboola mcp server

Keboola MCP Server

Provides an open-source bridge to Keboola data and transformations, enabling AI agents to access storage, SQL, jobs, and workflows.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "keboola-keboola-mcp-server": {
      "url": "https://mcp.<YOUR_REGION>.keboola.com/mcp",
      "headers": {
        "KBC_BRANCH_ID": "123456",
        "KBC_STORAGE_TOKEN": "your_keboola_storage_token",
        "KBC_STORAGE_API_URL": "https://connection.YOUR_REGION.keboola.com",
        "KBC_WORKSPACE_SCHEMA": "your_workspace_schema"
      }
    }
  }
}

Keboola MCP Server acts as a bridge between your Keboola project and modern AI assistants, enabling you to expose storage, SQL transformations, jobs, and workflows as callable tools. It lets you query data, manage components, run jobs, and orchestrate workflows from AI agents like Claude, Cursor, Windsurf, and more, with secure access to your Keboola project and development branches when needed.

How to use

Connect your MCP client ( Claude, Cursor, Windsurf, or another compatible AI assistant) to Keboola MCP Server using either the remote HTTP-based server or the local/stdio option. Once connected, you can explore your Keboola data, build SQL transformations with natural language prompts, run component jobs, and manage flows and data apps directly from your AI assistant. Begin with simple data discovery, then scale to complex pipelines and metadata queries.

How to install

Prerequisites you need before installing Keboola MCP Server:

- Python 3.10+ and a Keboola project with admin rights

- uv (the UI runtime for running the MCP server) installed on your system

Choose one of the installation options below and follow the steps exactly.

Option A: Integrated Mode (Recommended)

Integrated mode lets Claude or Cursor automatically start the MCP server when needed. You do not run any commands in the terminal; the client launches the MCP server on demand.

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

Option B: Local Development Mode

If you are developing or testing the MCP server locally, clone the repository, set credentials, install dependencies, and run the server from your environment.

{
  "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_STORAGE_TOKEN": "your_keboola_storage_token",
        "KBC_WORKSPACE_SCHEMA": "your_workspace_schema",
        "KBC_BRANCH_ID": "your_branch_id_optional"
      }
    }
  }
}

Option C: Manual CLI Mode (For Testing Only)

Run the server manually in a terminal for testing or debugging. This mode is mainly for quick checks and development.

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
export KBC_BRANCH_ID=your_branch_id_optional

uvx keboola_mcp_server --transport sse

Option D: Using Docker

Run Keboola MCP Server in a Docker container for isolated, repeatable runs.

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_KBC_STORAGE_TOKEN" \
  -e KBC_WORKSPACE_SCHEMA="YOUR_WORKSPACE_SCHEMA" \
  -e KBC_BRANCH_ID="YOUR_BRANCH_ID_OPTIONAL" \
  keboola/mcp-server:latest \
  --transport sse \
  --host 0.0.0.0

Do I Need to Start the Server Myself?

Yes, in some scenarios you will start it manually or configure it in your AI client. In integrated mode you don’t need to start it; otherwise follow the chosen option above to start or point your client to the running server.

Using MCP Server

Once your MCP client is configured and connected, you can begin querying Keboola data, exploring storage tables, creating SQL transformations, running jobs, and orchestrating workflows from your AI assistant. Try simple queries first, then expand to more advanced data pipelines across your Keboola project.

Compatibility

The MCP Server supports multiple clients and transports, including HTTP for remote access and stdio for local integrations. Ensure you provide Keboola credentials in the appropriate mode and scope operations to the correct Keboola development branch when using development work.

Security and Access

Use your Keboola master or restricted storage tokens to control the server’s access level. If you want limited access, use a custom storage token; for full access, use the master token. When using development branches, include the branch ID so all operations are scoped to that branch.

Troubleshooting

Common issues include authentication errors, workspace misconfigurations, or network timeouts. Verify tokens, workspace schema, and network connectivity; re-authenticate if required; and ensure the correct branch scope is applied when using development branches.

Development

For development workflows, you can run integration tests locally after setting the required storage API URL, token, and workspace schema. Use the uv tool to synchronize and run tests as described in your development plan.