mcp-server

[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/keboola/mcp-server)

# Keboola MCP Server

> 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.

## Overview

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](#-quick-start-remote-mcp-server-easiest-way)
- [Local Setup](#local-mcp-server-setup-custom-or-dev-way)

## Features

With the AI Agent and MCP Server, you can:

- **Storage**: Query tables directly and manage table or bucket descriptions
- **Components**: Create, List and inspect extractors, writers, data apps, and transformation configurations
- **SQL**: Create SQL transformations with natural language
- **Jobs**: Run components and transformations, and retrieve job execution details
- **Flows**: Build and manage workflow pipelines using Conditional Flows and Orchestrator Flows.
- **Data Apps**: Create, deploy and manage Keboola Streamlit Data Apps displaying your queries over storage data.
- **Metadata**: Search, read, and update project documentation and object metadata using natural language
- **Dev Branches**: Work safely in development branches outside of production, where all operations are scoped to the selected branch.

---

## 🚀 Quick Start: Remote MCP Server (Easiest Way)

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.

### What is the Remote MCP Server?

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.

### How to Connect

1. **Get your remote server URL**: Navigate to your Keboola Project Settings → `MCP Server` tab
2. **Copy the server URL**: It will look like `https://mcp.<YOUR_REGION>.keboola.com/mcp`
3. **Configure your AI assistant**: Paste the URL into your AI assistant's MCP settings
4. **Authenticate**: You'll be prompted to log in with your Keboola account. Which project(s) to work on is chosen afterwards, in the conversation (e.g. "list my Keboola projects" / "use project X")

### Supported Clients

- **[Cursor](https://cursor.com)**: Use the "Install In Cursor" button in your project's MCP Server settings or click
  this button
  [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=keboola&config=eyJ1cmwiOiJodHRwczovL21jcC51cy1lYXN0NC5nY3Aua2Vib29sYS5jb20vbWNwIn0%3D)
- **[Claude Desktop](https://claude.ai)**: Add the integration via Settings → Integrations
- **[Claude Code](https://www.anthropic.com/)**: Install using `claude mcp add --transport http keboola <URL>` (see below for details)
- **[Windsurf](https://windsurf.ai)**: Configure with the remote server URL
- **[Make](https://make.com)**: Configure with the remote server URL
- **Other MCP clients**: Configure with the remote server URL

#### Claude Code Setup

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:

```bash
claude mcp add --transport http keboola https://mcp.<YOUR_REGION>.keboola.com/mcp
```

**Region-specific commands:**

| Region | Installation Command |
|--------|----------------------|
| US Virginia AWS | `claude mcp add --transport http keboola https://mcp.keboola.com/mcp` |
| US Virginia GCP | `claude mcp add --transport http keboola https://mcp.us-east4.gcp.keboola.com/mcp` |
| EU Frankfurt AWS | `claude mcp add --transport http keboola https://mcp.eu-central-1.keboola.com/mcp` |
| EU Ireland Azure | `claude mcp add --transport http keboola https://mcp.north-europe.azure.keboola.com/mcp` |
| EU Frankfurt GCP | `claude mcp add --transport http keboola https://mcp.europe-west3.gcp.keboola.com/mcp` |

**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:
1. Log in with your Keboola account
2. Authorize the connection

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](https://help.keboola.com/ai/mcp-server/#remote-server-setup).

### Using Development Branches
You 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.

### Tool Authorization and Access Control

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.

#### Authorization Headers

| Header | Description | Example |
|--------|-------------|---------|
| `X-Allowed-Tools` | Comma-separated list of allowed tools | `get_configs,get_buckets,query_data` |
| `X-Disallowed-Tools` | Comma-separated list of tools to exclude | `create_config,run_job` |
| `X-Read-Only-Mode` | Restrict to read-only tools only | `true`, `1`, or `yes` |

#### Filter Behavior

Filters apply in order: allowed → read-only intersection → disallowed exclusion. Empty headers = no restriction.

#### Read-Only Tools

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](TOOLS.md) file which is an auto-generated snapshot of the actual tool set.

#### Example: Read-Only Access

```
X-Read-Only-Mode: true
```

#### Deferred Tool Loading

| Header | Description | Example |
|--------|-------------|---------|
| `X-Deferred-Tools` | Comma-separated list of tools to list with `_meta["anthropic/alwaysLoad"] = false` | `run_sync_action,get_flow_schema` |

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](https://developers.keboola.com/integrate/mcp/#tool-authorization-and-access-control).

---

## Local MCP Server Setup (Custom or Dev Way)

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 <url>/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](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 va