Skip to content
Back to search

mcp-server

Model Context Protocol (MCP) Server for the Keboola Platform

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/keboola/mcp-server with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/keboola/mcp-server'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/keboola--mcp-server/badge.svg)](/listings/keboola--mcp-server)

HTML

<a href="/listings/keboola--mcp-server"><img src="/api/listings/keboola--mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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 - **[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:

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 621 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/keboola/mcp-server)
  2. # Keboola MCP Server
  3. > 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.
  4. ## Overview
  5. 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.
  6. - [Quick Start](#-quick-start-remote-mcp-server-easiest-way)
  7. - [Local Setup](#local-mcp-server-setup-custom-or-dev-way)
  8. ## Features
  9. With the AI Agent and MCP Server, you can:
  10. - **Storage**: Query tables directly and manage table or bucket descriptions
  11. - **Components**: Create, List and inspect extractors, writers, data apps, and transformation configurations
  12. - **SQL**: Create SQL transformations with natural language
  13. - **Jobs**: Run components and transformations, and retrieve job execution details
  14. - **Flows**: Build and manage workflow pipelines using Conditional Flows and Orchestrator Flows.
  15. - **Data Apps**: Create, deploy and manage Keboola Data Apps displaying your queries over storage data — python-js apps on a Keboola-managed repository or on a customer GitHub repository (cloned through the organization's GitHub connection, no stored credential), and Streamlit apps.
  16. - **Metadata**: Search, read, and update project documentation and object metadata using natural language
  17. - **Dev Branches**: Work safely in development branches outside of production, where all operations are scoped to the selected branch.
  18. ---
  19. ## 🚀 Quick Start: Remote MCP Server (Easiest Way)
  20. 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.
  21. ### What is the Remote MCP Server?
  22. 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.
  23. ### How to Connect
  24. 1. **Get your remote server URL**: Navigate to your Keboola Project Settings → `MCP Server` tab
  25. 2. **Copy the server URL**: It will look like `https://mcp.<YOUR_REGION>.keboola.com/mcp`
  26. 3. **Configure your AI assistant**: Paste the URL into your AI assistant's MCP settings
  27. 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")
  28. ### Supported Clients
  29. - **[Cursor](https://cursor.com)**: Use the "Install In Cursor" button in your project's MCP Server settings or click
  30. this button
  31. [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=keboola&config=eyJ1cmwiOiJodHRwczovL21jcC51cy1lYXN0NC5nY3Aua2Vib29sYS5jb20vbWNwIn0%3D)
  32. - **[Claude Desktop](https://claude.ai)**: Add the integration via Settings → Integrations
  33. - **[Claude Code](https://www.anthropic.com/)**: Install using `claude mcp add --transport http keboola <URL>` (see below for details)
  34. - **[Windsurf](https://windsurf.ai)**: Configure with the remote server URL
  35. - **[Make](https://make.com)**: Configure with the remote server URL
  36. - **Other MCP clients**: Configure with the remote server URL
  37. #### Claude Code Setup
  38. 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.
  39. **Installation:**
  40. Run the following command in your terminal, replacing `<YOUR_REGION>` with your Keboola region:
  41. ```bash
  42. claude mcp add --transport http keboola https://mcp.<YOUR_REGION>.keboola.com/mcp
  43. ```
  44. **Region-specific commands:**
  45. | Region | Installation Command |
  46. |--------|----------------------|
  47. | US Virginia AWS | `claude mcp add --transport http keboola https://mcp.keboola.com/mcp` |
  48. | US Virginia GCP | `claude mcp add --transport http keboola https://mcp.us-east4.gcp.keboola.com/mcp` |
  49. | EU Frankfurt AWS | `claude mcp add --transport http keboola https://mcp.eu-central-1.keboola.com/mcp` |
  50. | EU Ireland Azure | `claude mcp add --transport http keboola https://mcp.north-europe.azure.keboola.com/mcp` |
  51. | EU Frankfurt GCP | `claude mcp add --transport http keboola https://mcp.europe-west3.gcp.keboola.com/mcp` |
  52. **Usage:**
  53. 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.
  54. **Authentication:**
  55. When you first use the Keboola MCP Server in Claude Code, a browser window will open prompting you to:
  56. 1. Log in with your Keboola account
  57. 2. Authorize the connection
  58. 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.
  59. For detailed setup instructions and region-specific URLs, see our [Remote Server Setup documentation](https://help.keboola.com/ai/mcp-server/#remote-server-setup).
  60. ### Using Development Branches
  61. 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.
  62. ### Tool Authorization and Access Control
  63. 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.
  64. #### Authorization Headers
  65. | Header | Description | Example |
  66. |--------|-------------|---------|
  67. | `X-Allowed-Tools` | Comma-separated list of allowed tools | `get_configs,get_buckets,query_data` |
  68. | `X-Disallowed-Tools` | Comma-separated list of tools to exclude | `create_config,run_job` |
  69. | `X-Read-Only-Mode` | Restrict to read-only tools only | `true`, `1`, or `yes` |
  70. #### Filter Behavior
  71. Filters apply in order: allowed → read-only intersection → disallowed exclusion. Empty headers = no restriction.
  72. #### Read-Only Tools
  73. 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.
  74. #### Example: Read-Only Access
  75. ```
  76. X-Read-Only-Mode: true
  77. ```
  78. #### Deferred Tool Loading
  79. | Header | Description | Example |
  80. |--------|-------------|---------|
  81. | `X-Deferred-Tools` | Comma-separated list of tools to list with `_meta["anthropic/alwaysLoad"] = false` | `run_sync_action,get_flow_schema` |
  82. 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.
  83. 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).
  84. ### Row-Level and Column-Level Security
  85. Row- and column-level policies are Keboola Metastore objects (`rls-policy`, `cls-policy`), written through the Metastore
  86. API (the `kbagent rls` / `kbagent cls` commands are not in any kbagent release yet). This server neither reads nor
  87. applies them. In a project that has the `row-level-security` feature it creates its workspace (the `mcp-workspace-<hex>`
  88. configuration of the `keboola.mcp-server-tool` component) with the Connection login type `governed`. A governed
  89. workspace has no credentials: only the Query Service can read it, and the Query Service filters every `query_data`
  90. result by the policies of the project. There is no rewriting in this server and no fallback: what the Query Service
  91. refuses, `query_data` returns as an error.
  92. - **What turns it on.** The project feature is checked by this server only; Connection needs no feature or role to
  93. create a governed workspace (Snowflake or BigQuery, no public key). The stack's Connection must accept the login type
  94. `governed` for the project's backend: a stack that does not refuses the create, and then every tool that needs the
  95. workspace fails (there is no fallback to an ordinary workspace). Enforcement on BigQuery is not verified end to end on
  96. a production stack. An older ordinary MCP workspace is not deleted: it is skipped as soon as the feature is on. With
  97. the feature on, a `workspace_schema` or `X-Workspace-Id` pin is accepted only for a governed workspace (an ordinary
  98. one would read around the policies), so a pin to the old workspace, or to a data app's own ordinary workspace, is
  99. refused; delete the old one.
  100. - **Deny by default.** A table that neither an `rls-policy` nor a `cls-policy` covers is refused for an administrator
  101. (the agent sees `Row-level security does not allow this query`) and reads as no rows for an ordinary reader such as a
  102. data app end user (a `"*"` rule opens a table to every identified reader). A `cls-policy` alone opens its table: all
  103. rows, only its columns, for the readers it names; any other reader is refused. A statement that reads no table
  104. (`SELECT 1`) runs.
  105. - **Refused statements.** A governed statement is refused (403, the same generic text for every reason) when it uses
  106. `IDENTIFIER()`, `TABLE()` outside `FROM`, an AI function (`AI_*`, BigQuery `AI.*`), `TO_FILE`, `READ_CSV` /
  107. `READ_PARQUET`, `SECRET`, a session-context function (`CURRENT_USER`, `CURRENT_ROLE`, `CURRENT_STATEMENT`, ...),
  108. `NEXTVAL`, `$x` or `@@x`, a control character, or an unquoted name with a non-ASCII character or `$$`, or when it is
  109. over 32 KiB, 200 CTEs or 300 table references. `CURRENT_DATE`, `CURRENT_TIME` and `CURRENT_TIMESTAMP` stay allowed (as
  110. of Query Service 1.25 and policy engine 0.1.8). A 503 `Row-level security could not be applied to this workspace`
  111. means nothing ran because the policies could not be applied; it can be transient. A failed governed statement returns
  112. `The statement failed. Its error text is not shown for a workspace with row-level security`.
  113. - **Who is the reader.** The Query Service resolves the reader from the administrator's own token of the project: the
  114. programmatic token this server forwards (`kbc_at_` / `kbc_pat_`, including the child PAT of a multi-project scope,
  115. sent with `X-KBC-ProjectId`) or an administrator's own master Storage token. Any other token (an integration, a data
  116. app, Kai) names no end user, has no verified identity and reads nothing from a governed table. The administrator's
  117. subject is `keboola|<adminId>` and the identity carries no groups, so group rules never match.
  118. - **Bindings.** Without a binding a workspace gets every policy of the project, and this server never creates one. To
  119. give a workspace only some policies, bind them to its KID:
  120. `KID:<stack-id>:project-<project-id>:workspace-<workspace-id>` (a workspace of the default branch; a branch workspace
  121. also has `branch-<branch-id>` before `project`). The stack id is the one the Query Service is configured with
  122. (`QUERY_RLS_STACK_ID`, for example `dev-keboola-aws-eu-west-1`), the workspace id is in the `get_project_info` output,
  123. and a `policy-binding` Metastore object with that KID writes the binding (no kbagent command for it is released yet).
  124. A binding is an allowlist: it keeps only the policies it lists, so it can leave out any policy, an organization-scope
  125. one included, and loosen access. One that lists no `rls-policy` drops every row policy, so a table covered by a kept
  126. `cls-policy` opens with all rows. A binding applies to the next query and does not follow the session to another
  127. workspace: a branch session, or a workspace that is recreated, has a new KID and starts again with every policy.
  128. - **Limits.** The workspace id of the server's workspace is also what a data app gets as `WORKSPACE_ID` when no separate
  129. workspace is provisioned for it; the app queries with its own token, has no verified identity, and reads nothing from
  130. governed tables.
  131. - **Metadata.** The metadata tools show only what the Query Service lets the reader read. `get_tables` and `search`
  132. (which then does not use the global search, as its counts include the hidden tables) leave out a table the reader may
  133. not read, and `get_tables` reports one that was asked for by ID as not found; a table with a column policy shows only
  134. the columns of the policy (also in its primary key and in what `search` matches). A readable table is shown without
  135. its number of rows and its size, which count the rows that a row policy hides. `get_buckets` still lists every bucket,
  136. but without the number of tables and the size, which count the hidden tables. This needs the Query Service endpoint
  137. `POST /api/v1/branches/{branch}/workspaces/{workspace}/rls/scope`, and fails closed: when the Query Service cannot
  138. say, a tool of a governed project returns an error with a short message and no table. A project without the feature is
  139. not affected and makes no extra call.
  140. ---
  141. ## Local MCP Server Setup (Custom or Dev Way)
  142. 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.
  143. The server supports multiple **transport** options, which can be selected by providing the `--transport <transport>` argument when starting the server:
  144. - `stdio` - Default when `--transport` is not specified. Standard input/output, typically used for local deployment with a single client.
  145. - `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).
  146. - `http-compat` - An alias for `streamable-http`, kept for backwards compatibility.
  147. 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.
  148. Some of the variables are not taken from the request headers:
  149. - `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.
  150. - `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.
  151. - `KBC_WORKSPACE_ID` / `KBC_WORKSPACE_SCHEMA`: same idea as the Storage API URL above — a server started with its own workspace pin (via either variable, or `--workspace-id`) keeps that pin for every request; an `X-Workspace-Id` or `X-Workspace-Schema` header asking for a different workspace is ignored (a warning is logged). A server with no pin of its own (the shared multi-user case) keeps taking the pin from the request, per-request, as described below.
  152. ### Logging in
  153. Sign in once with your browser; the server stores the session and refreshes it automatically, so there are no tokens to manage:
  154. ```bash
  155. uvx keboola_mcp_server login --api-url https://connection.YOUR_REGION.keboola.com
  156. ```
  157. This opens your browser to sign in to Keboola, then saves the stack-wide session to `~/.keboola/mcp/credentials.json` (readable only by you, one entry per stack). Afterwards, start the server with only `KBC_STORAGE_API_URL` set — no token required. Which project(s) to work on is chosen afterwards, in the conversation (`get_accessible_projects` / `set_project_scope`), not during login.
  158. | Command | What it does |
  159. |---------|--------------|
  160. | `login --api-url <url>` | Sign in to a stack |
  161. | `login --force` | Sign in again / switch account |
  162. | `login --show-token` | Print the current session token (debugging) |
  163. | `logout [--api-url <url>] [--all]` | Remove the stored session for a stack (or all stacks) |
  164. When you start the server over **stdio in an interactive terminal** with no stored session, it runs this browser login automatically on first start. MCP clients (Claude, Cursor, …) launch the server in the background where a browser can't open, so run `login` once yourself first.
  165. #### Starting without a Keboola account
  166. You can also start the server with only `KBC_STORAGE_API_URL` and no credentials at all. It comes up in *bootstrap mode*: tools that need Keboola access explain how to get a credential, and one tool works without one — `create_project`. It creates a new Keboola project, signs the session in to it, and returns a confirmation URL. Opening that URL in a browser and signing in makes the project permanently yours; until then it is temporary and Keboola may reclaim it, and once you confirm, the session the tool created is revoked and you continue with your own `login`.
  167. This needs a stack with agent provisioning enabled; elsewhere the tool reports that it is not available.
  168. The same thing is possible without running a server at all, on a **remotely hosted** MCP server whose
  169. operator has enabled it (`KBC_ALLOW_ANONYMOUS_PROVISIONING`): such a deployment also serves
  170. `https://mcp.<stack>/mcp-anonymous`, which accepts no credentials. Point your client there with no
  171. authentication, call `create_project`, and keep working in the project that call created — the server
  172. holds its credentials for you and the tool hands back an opaque `scope_token` to resend on later
  173. calls. It is a separate URL because the ordinary `/mcp` endpoint has to keep refusing unauthenticated
  174. requests: that refusal is how MCP clients know to start the OAuth login. Once you claim the project,
  175. switch to `/mcp` and sign in with the account that now owns it.
  176. #### Authenticating without a browser
  177. For containers or CI where a browser login isn't possible, provide a Keboola [access or personal access token](https://help.keboola.com/management/project/tokens/) directly — set `KBC_STORAGE_TOKEN` (env var) or send the `X-StorageAPI-Token` header — together with `KBC_PROJECT_ID` (or the `X-KBC-ProjectId` header) to select the project. On HTTP transports these can be supplied per request as headers, so each request carries its own credentials.
  178. ### KBC_WORKSPACE_ID
  179. Pins queries to one specific, already-existing workspace by its ID instead of the schema-based lookup above, and takes precedence over `KBC_WORKSPACE_SCHEMA` when both are set. This is the option a Data App / kai-agent caller supplies, as the `X-Workspace-Id` header, so that Kai embedded in that app queries only through its own workspace.
  180. Set via the `KBC_WORKSPACE_ID` environment variable, the `--workspace-id` CLI flag, or (per-request, for multi-user deployments) the `X-Workspace-Id` header.
  181. ### KBC_WORKSPACE_SCOPE
  182. `strict` limits a session to its pinned workspace, for Kai in a Data App whose workspace has direct-grant input mapping. The session then:
  183. - offers only `query_data`, `get_buckets`, `get_tables`, `get_project_info` and `docs_query`, whatever the authorization headers say (they can narrow this list further, not widen it);
  184. - never looks up or creates the MCP-managed workspace and never fans out across projects;
  185. - refuses a workspace with read-only access to the whole Storage, and refuses configuration previews.
  186. It requires a workspace pin (`KBC_WORKSPACE_ID` / `X-Workspace-Id`). `strict` is the only accepted value, so a request can tighten a session but never loosen a server-side `strict`. Set via the `KBC_WORKSPACE_SCOPE` environment variable or, per request, the `X-Workspace-Scope` header.
  187. ### KBC_STORAGE_API_URL (Keboola Region)
  188. Your 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:
  189. | Region | API URL |
  190. |--------|---------|
  191. | AWS North America | `https://connection.keboola.com` |
  192. | AWS Europe | `https://connection.eu-central-1.keboola.com` |
  193. | Google Cloud EU | `https://connection.europe-west3.gcp.keboola.com` |
  194. | Google Cloud US | `https://connection.us-east4.gcp.keboola.com` |
  195. | Azure EU | `https://connection.north-europe.azure.keboola.com` |
  196. ### KBC_BRANCH_ID (Optional)
  197. To 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.
  198. - If not provided, the server uses the production branch by default.
  199. - 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`.
  200. - On remote transports, you can override per-request with the HTTP header `X-Branch-Id: <branchId>` or `KBC_BRANCH_ID: <branchId>`.
  201. ### Installation
  202. Make sure you have:
  203. - [ ] Python 3.11+ installed
  204. - [ ] Access to a Keboola project with admin rights
  205. - [ ] Your preferred MCP client (Claude, Cursor, etc.)
  206. **Note**: Make sure you have `uv` installed. The MCP client will use it to automatically download and run the Keboola MCP Server.
  207. **Installing uv**:
  208. *macOS/Linux*:
  209. ```bash
  210. #if homebrew is not installed on your machine use:
  211. # /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  212. # Install using Homebrew
  213. brew install uv
  214. ```
  215. *Windows*:
  216. ```powershell
  217. # Using the installer script
  218. powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  219. # Or using pip
  220. pip install uv
  221. # Or using winget
  222. winget install --id=astral-sh.uv -e
  223. ```
  224. For more installation options, see the [official uv documentation](https://docs.astral.sh/uv/getting-started/installation/).
  225. ### Running Keboola MCP Server
  226. There are four ways to use the Keboola MCP Server, depending on your needs:
  227. ### Option A: Integrated Mode (Recommended)
  228. In this mode, Claude or Cursor automatically starts the MCP server for you.
  229. 1. **Log in once** in a terminal so a session is stored (the client launches the server in the background, where a browser can't open):
  230. ```bash
  231. uvx keboola_mcp_server login --api-url https://connection.YOUR_REGION.keboola.com
  232. ```
  233. 2. Configure your MCP client (Claude/Cursor) with the settings below — only `KBC_STORAGE_API_URL` is needed.
  234. 3. The client will automatically launch the MCP server when needed.
  235. #### Claude Desktop Configuration
  236. 1. 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)
  237. 2. Add the following configuration:
  238. 3. Restart Claude desktop for changes to take effect
  239. ```json
  240. {
  241. "mcpServers": {
  242. "keboola": {
  243. "command": "uvx",
  244. "args": ["keboola_mcp_server --transport <transport>"],
  245. "env": {
  246. "KBC_STORAGE_API_URL": "https://connection.YOUR_REGION.keboola.com",
  247. "KBC_BRANCH_ID": "your_branch_id_optional"
  248. }
  249. }
  250. }
  251. }
  252. ```
  253. Config file locations:
  254. - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  255. - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  256. #### Cursor Configuration
  257. 1. Go to Settings → MCP
  258. 2. Click "+ Add new global MCP Server"
  259. 3. Configure with these settings:
  260. ```json
  261. {
  262. "mcpServers": {
  263. "keboola": {
  264. "command": "uvx",
  265. "args": ["keboola_mcp_server --transport <transport>"],
  266. "env": {
  267. "KBC_STORAGE_API_URL": "https://connection.YOUR_REGION.keboola.com",
  268. "KBC_BRANCH_ID": "your_branch_id_optional"
  269. }
  270. }
  271. }
  272. }
  273. ```
  274. **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.
  275. #### Cursor Configuration for Windows WSL
  276. When running the MCP server from Windows Subsystem for Linux with Cursor AI, use this configuration:
  277. ```json
  278. {
  279. "mcpServers": {
  280. "keboola":{
  281. "command": "wsl.exe",
  282. "args": [
  283. "bash",
  284. "-c '",
  285. "export KBC_STORAGE_API_URL=https://connection.YOUR_REGION.keboola.com &&",
  286. "export KBC_BRANCH_ID=your_branch_id_optional &&",
  287. "/snap/bin/uvx keboola_mcp_server --transport <transport>",
  288. "'"
  289. ]
  290. }
  291. }
  292. }
  293. ```
  294. ### Option B: Local Development Mode
  295. For developers working on the MCP server code itself:
  296. 1. Clone the repository and set up a local environment
  297. 2. Configure Claude/Cursor to use your local Python path:
  298. ```json
  299. {
  300. "mcpServers": {
  301. "keboola": {
  302. "command": "/absolute/path/to/.venv/bin/python",
  303. "args": [
  304. "-m",
  305. "keboola_mcp_server --transport <transport>"
  306. ],
  307. "env": {
  308. "KBC_STORAGE_API_URL": "https://connection.YOUR_REGION.keboola.com",
  309. "KBC_BRANCH_ID": "your_branch_id_optional"
  310. }
  311. }
  312. }
  313. }
  314. ```
  315. ### Option C: Manual CLI Mode (For Testing Only)
  316. You can run the server manually in a terminal for testing or debugging:
  317. ```bash
  318. # Sign in once (stores a session under ~/.keboola/mcp), then start the server.
  319. export KBC_STORAGE_API_URL=https://connection.YOUR_REGION.keboola.com
  320. uvx keboola_mcp_server login --api-url "$KBC_STORAGE_API_URL"
  321. uvx keboola_mcp_server --transport streamable-http
  322. ```
  323. > **Note**: This mode is primarily for debugging or testing. For normal use with Claude or Cursor,
  324. > you do not need to manually run the server.
  325. > **Note**: The server will use the Streamable HTTP transport and listen on `localhost:8000` for incoming connections at `/mcp`.
  326. > You can use `--port` and `--host` parameters to make it listen elsewhere.
  327. ### Option D: Using Docker
  328. A container can't open a browser, so authenticate with a token (see [Authenticating without a browser](#authenticating-without-a-browser)): set `KBC_STORAGE_TOKEN` to a Keboola access/personal access token and `KBC_PROJECT_ID` to the target project. (Over HTTP you can instead pass `X-StorageAPI-Token` / `X-KBC-ProjectId` headers per request and omit these.)
  329. ```shell
  330. docker pull keboola/mcp-server:latest
  331. docker run \
  332. --name keboola_mcp_server \
  333. --rm \
  334. -it \
  335. -p 127.0.0.1:8000:8000 \
  336. -e KBC_STORAGE_API_URL="https://connection.YOUR_REGION.keboola.com" \
  337. -e KBC_STORAGE_TOKEN="YOUR_KEBOOLA_TOKEN" \
  338. -e KBC_PROJECT_ID="YOUR_PROJECT_ID" \
  339. -e KBC_BRANCH_ID="YOUR_BRANCH_ID_OPTIONAL" \
  340. keboola/mcp-server:latest \
  341. --transport streamable-http \
  342. --host 0.0.0.0
  343. ```
  344. > **Note**: The server will use the Streamable HTTP transport and listen on `localhost:8000` for incoming connections at `/mcp`.
  345. > You can change `-p` to map the container's port somewhere else.
  346. ### Do I Need to Start the Server Myself?
  347. | Scenario | Need to Run Manually? | Use This Setup |
  348. |----------|----------------------|----------------|
  349. | Using Claude/Cursor | No | Configure MCP in app settings |
  350. | Developing MCP locally | No (Claude starts it) | Point config to python path |
  351. | Testing CLI manually | Yes | Use terminal to run |
  352. | Using Docker | Yes | Run docker container |
  353. ## Using MCP Server
  354. Once your MCP client (Claude/Cursor) is configured and running, you can start querying your Keboola data:
  355. ### Verify Your Setup
  356. You can start with a simple query to confirm everything is working:
  357. ```text
  358. What buckets and tables are in my Keboola project?
  359. ```
  360. ### Examples of What You Can Do
  361. **Data Exploration:**
  362. - "What tables contain customer information?"
  363. - "Run a query to find the top 10 customers by revenue"
  364. **Data Analysis:**
  365. - "Analyze my sales data by region for the last quarter"
  366. - "Find correlations between customer age and purchase frequency"
  367. **Data Pipelines:**
  368. - "Create a SQL transformation that joins customer and order tables"
  369. - "Start the data extraction job for my Salesforce component"
  370. ## Compatibility
  371. ### MCP Client Support
  372. | **MCP Client** | **Support Status** | **Connection Method** |
  373. |----------------|-------------------|----------------------|
  374. | Claude (Desktop & Web) | ✅ supported | stdio |
  375. | Cursor | ✅ supported | stdio |
  376. | Windsurf, Zed, Replit | ✅ Supported | stdio |
  377. | Codeium, Sourcegraph | ✅ Supported | Streamable HTTP |
  378. | Custom MCP Clients | ✅ Supported | Streamable HTTP or stdio |
  379. ## Supported Tools
  380. **Note:** Your AI agents will automatically adjust to new tools.
  381. For a complete list of available tools with detailed descriptions, parameters, and usage examples, see [TOOLS.md](TOOLS.md).
  382. ## Troubleshooting
  383. ### Common Issues
  384. | Issue | Solution |
  385. |-------|----------|
  386. | **Authentication Errors** | Re-run `keboola_mcp_server login` (or, if authenticating with a token, verify the token and `KBC_PROJECT_ID`) |
  387. | **Connection Timeout** | Check network connectivity |
  388. ## Development
  389. ### Installation
  390. Basic setup:
  391. ```bash
  392. uv sync --extra dev
  393. ```
  394. With the basic setup, you can use `uv run tox` to run tests and check code style.
  395. Recommended setup:
  396. ```bash
  397. uv sync --extra dev --extra tests --extra integtests --extra codestyle
  398. ```
  399. With the recommended setup, packages for testing and code style checking will be installed which allows IDEs like
  400. VsCode or Cursor to check the code or run tests during development.
  401. ### Integration tests
  402. To run integration tests locally, use `uv run tox -e integtests`.
  403. NOTE: You will need to set the following environment variables:
  404. - `INTEGTEST_POOL_STORAGE_API_URL`
  405. - `INTEGTEST_STORAGE_TOKENS`
  406. - `INTEGTEST_STORAGE_TOKEN_STORAGE_BRANCHES`
  407. In order to get these values, you need dedicated Keboola projects for integration tests.
  408. Each test session creates its own read-only workspace, so no workspace schema needs to be
  409. configured. See `integtests/README.md` for detailed setup instructions and design documentation.
  410. ### Updating `uv.lock`
  411. Update the `uv.lock` file if you have added or removed dependencies. Also consider updating the lock with newer dependency
  412. versions when creating a release (`uv lock --upgrade`).
  413. ### Updating Tool Documentation
  414. When you make changes to any tool descriptions (docstrings in tool functions), you must regenerate the `TOOLS.md` documentation file to reflect these changes:
  415. ```bash
  416. uv run python -m src.keboola_mcp_server.generate_tool_docs
  417. ```
  418. ### Releasing
  419. We do **not** cut a release for every merged PR. Work lands on the trunk (`main`)
  420. continuously, and we release periodically once changes have been re-tested together —
  421. this avoids breaking working setups for users.
  422. A release is made by pushing **one or two git tags**:
  423. - `vX.Y.Z` — the MCP server release (always)
  424. - `agent-vX.Y.Z` — the In Platform Agent release (only when the agent is being released too)
  425. Either tag triggers `release.yml` CI, which builds and publishes the Docker image. KaiBench
  426. runs only on production `vX.Y.Z` tags (not `agent-vX.Y.Z`, and not `-dev.` prereleases). Use
  427. the `release-notes` skill — it prepares the release notes and draft PR and walks through
  428. tagging both `vX.Y.Z` and `agent-vX.Y.Z`.
  429. ## Support and Feedback
  430. **⭐ 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). ⭐**
  431. The development team actively monitors issues and will respond as quickly as possible. For general information about Keboola, please use the resources below.
  432. ## Resources
  433. - [User Documentation](https://help.keboola.com/)
  434. - [Developer Documentation](https://developers.keboola.com/)
  435. - [Keboola Platform](https://www.keboola.com)
  436. - [Issue Tracker](https://github.com/keboola/mcp-server/issues/new) ← **Primary contact method for MCP Server**
  437. ## Connect
  438. - [LinkedIn](https://www.linkedin.com/company/keboola)
  439. - [Twitter](https://x.com/keboola)
  440. - [Changelog](https://changelog.keboola.com/)
  441. [//]: # (mcp-name: com.keboola/mcp -- keep this line for registry.modelcontextprotocol.io)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.