Skip to main content
Glama
davidesner

keboola-cli-mcp-server

by davidesner
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

Keboola CLI MCP Server

A Model Context Protocol (MCP) server that acts as a deterministic proxy for Keboola CLI (kbc) operations, with automatic git-to-Keboola branch mapping.

Overview

This server ensures agents cannot accidentally use the wrong Keboola branch by enforcing branch resolution before any CLI command execution. It provides:

  • Deterministic branch resolution: Always derives the current git branch programmatically

  • Fail-safe CLI proxy: All CLI commands must go through branch resolution

  • Single source of truth: branch-mapping.json is the authoritative mapping file

  • Project validation: Ensures the Keboola project is properly initialized with --allow-target-env

Related MCP server: Aurea Orchestrator MCP

Server Modes

The server supports two modes:

CLI Mode (Default)

Provides local CLI tools for running kbc commands with automatic branch context:

  • Branch management (link_branch, unlink_branch, etc.)

  • CLI proxy for kbc commands (sync push, sync pull, etc.)

  • Documentation search

Proxy Mode

Proxies to the remote Keboola MCP server with automatic X-Branch-Id header injection:

  • All remote Keboola MCP tools (SQL workspace, table operations, jobs, etc.)

  • Plus local CLI tools (branch management, kbc commands)

  • Dynamic branch resolution per-request - switching git branches immediately takes effect

Enable with: KBC_MCP_PROXY_MODE=true

┌─────────────────────────────────────────────────────────────────────┐
│                         Proxy Mode Flow                              │
│                                                                      │
│  1. Claude calls any tool (e.g., "sql_query")                       │
│                    │                                                 │
│                    ▼                                                 │
│  2. client_factory() called  ◄── PER REQUEST                        │
│       ├── git branch --show-current → "feature/billing"             │
│       ├── branch-mapping.json → "22750"                             │
│       └── Headers: X-StorageAPI-Token, X-Branch-Id: 22750           │
│                    │                                                 │
│                    ▼                                                 │
│  3. Request forwarded to remote Keboola MCP server                  │
│     https://mcp-agent.{stack}.keboola.com/mcp                       │
│                    │                                                 │
│                    ▼                                                 │
│  4. Response returned to Claude                                      │
└─────────────────────────────────────────────────────────────────────┘

Prerequisites

  1. Keboola CLI (kbc) must be installed and available in your PATH

  2. Keboola project must be initialized with --allow-target-env

    kbc sync init --allow-target-env --storage-api-host connection.<region>.keboola.com

    This flag is required for the KBC_BRANCH_ID environment variable override to work.

  3. Python 3.10+

Installation

# Clone and install
git clone <repository>
cd keboola-cli-mcp-server
pip install -e .

Configuration

Environment Variables

Create a .env.local file in your Keboola project directory:

# Required - Keboola Storage API token
KBC_STORAGE_API_TOKEN=<your-storage-api-token>

# Required - Storage API host (without protocol, used to derive MCP server URL in proxy mode)
KBC_STORAGE_API_HOST=connection.<region>.keboola.com

# Optional - defaults shown
GIT_DEFAULT_BRANCH=main          # Default branch name (maps to production)
KBC_WORKING_DIR=.                # Working directory for CLI operations
KBC_MAPPING_FILE=branch-mapping.json  # Path to mapping file

# Proxy mode - enable to get remote Keboola MCP tools with branch injection
KBC_MCP_PROXY_MODE=false         # Set to "true" to enable proxy mode

MCP Client Setup

Claude Desktop

Add to your claude_desktop_config.json:

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

{
  "mcpServers": {
    "keboola-cli": {
      "command": "python",
      "args": ["-m", "keboola_cli_mcp_server"],
      "cwd": "/path/to/your/keboola-project",
      "env": {
        "KBC_STORAGE_API_TOKEN": "your-token-here"
      }
    }
  }
}

Cursor

Add to your .cursor/mcp.json in your project:

{
  "mcpServers": {
    "keboola-cli": {
      "command": "python",
      "args": ["-m", "keboola_cli_mcp_server"],
      "cwd": "${workspaceFolder}",
      "env": {
        "KBC_STORAGE_API_TOKEN": "your-token-here"
      }
    }
  }
}

Claude Code (CLI)

Add to your project's .mcp.json:

{
  "mcpServers": {
    "keboola-cli": {
      "command": "python",
      "args": ["-m", "keboola_cli_mcp_server"],
      "env": {
        "KBC_STORAGE_API_TOKEN": "your-token-here",
        "KBC_STORAGE_API_HOST": "connection.keboola.com"
      }
    }
  }
}

Proxy Mode Configuration

To enable proxy mode (recommended for full Keboola MCP functionality):

{
  "mcpServers": {
    "keboola-unified": {
      "command": "python",
      "args": ["-m", "keboola_cli_mcp_server"],
      "env": {
        "KBC_STORAGE_API_TOKEN": "your-token-here",
        "KBC_STORAGE_API_HOST": "connection.keboola.com",
        "KBC_MCP_PROXY_MODE": "true"
      }
    }
  }
}

This gives you access to:

  • All remote Keboola MCP tools (SQL workspace, table operations, etc.)

  • Local CLI tools (branch management, kbc commands)

  • Automatic branch resolution per-request

Available Tools

Branch Management

Tool

Description

link_branch

Links current git branch to a Keboola development branch. Creates new branch if needed.

unlink_branch

Removes the mapping for the current git branch (does not delete the Keboola branch).

get_mapping

Gets the mapping status for the current git branch.

list_mappings

Lists all git-to-Keboola branch mappings.

CLI Proxy

Tool

Description

kbc

Execute any allowed Keboola CLI command with automatic branch context.

Allowed commands:

  • sync push, sync pull, sync diff, sync init

  • remote job run, remote table preview/download/upload

  • remote create bucket, remote create branch, remote list branches

  • local validate, local create config, local encrypt

  • status

Documentation

Tool

Description

search_cli_docs

Search Keboola CLI documentation for commands, flags, and workflows.

Usage Example

User: "Push my changes to Keboola"

Agent: [calls kbc(command="sync push")]
       ↓
Server: BranchResolver.branch_context()
        → git branch --show-current → "feature/auth"
        → lookup mapping → NOT FOUND
        → Return NO_MAPPING error
       ↓
Agent: "I need to link this branch first"
       [calls link_branch()]
       ↓
Server: → Creates Keboola branch via CLI
        → Saves mapping to branch-mapping.json
        → Returns success with branch ID
       ↓
Agent: "Now I can push"
       [calls kbc(command="sync push")]
       ↓
Server: → Resolves branch → "972851"
        → Sets KBC_BRANCH_ID=972851
        → Runs: kbc sync push
        → Returns success

Error Handling

PROJECT_NOT_INITIALIZED

{
  "error": "PROJECT_NOT_INITIALIZED",
  "message": "PROJECT_MISCONFIGURED: The project was not initialized with --allow-target-env flag.",
  "fix": "Run 'kbc sync init --allow-target-env' to initialize the project properly"
}

Solution: Re-initialize your Keboola project with:

kbc sync init --allow-target-env --storage-api-host connection.<region>.keboola.com

NO_MAPPING

{
  "error": "NO_MAPPING",
  "message": "Git branch 'feature/new-thing' is not linked to any Keboola branch.",
  "git_branch": "feature/new-thing",
  "available_mappings": ["main", "feature/auth"]
}

Solution: Use the link_branch tool first to create a mapping.

Running the Server

# Run via stdio transport (default)
python -m keboola_cli_mcp_server

# Or use the entry point
keboola-cli-mcp

Development

Running Tests

pip install -e ".[dev]"
pytest tests/ -v

Project Structure

keboola-cli-mcp-server/
├── pyproject.toml
├── README.md
├── src/
│   └── keboola_cli_mcp_server/
│       ├── __init__.py
│       ├── __main__.py              # Entry point
│       ├── server.py                # FastMCP server setup
│       ├── config.py                # Configuration management
│       ├── tools/
│       │   ├── branch.py            # Branch management tools
│       │   ├── cli_proxy.py         # Generic kbc CLI proxy
│       │   └── docs.py              # Documentation search
│       ├── services/
│       │   ├── git.py               # Git operations
│       │   ├── branch_mapping.py    # Mapping file management
│       │   ├── branch_resolver.py   # Core resolution logic
│       │   └── sapi_client.py       # Storage API client
│       └── models/
│           └── schemas.py           # Pydantic models
└── tests/
    ├── test_branch_resolver.py
    ├── test_cli_proxy.py
    └── test_branch_tools.py

Branch Mapping File

The branch-mapping.json file stores git-to-Keboola branch mappings:

{
  "main": null,
  "feature/auth": "972851",
  "feature/data-pipeline": "983421"
}

  • Key: git branch name

  • Value: Keboola branch ID (string) or null for production

  • null means "use production branch, don't set KBC_BRANCH_ID"

Note: This file should be added to .gitignore as mappings may differ per developer.

How Branch Resolution Works

  1. Git branch detection: Runs git branch --show-current to get current branch

  2. Mapping lookup: Checks branch-mapping.json for a mapping

  3. Default branch handling: main/master branches map to production (no KBC_BRANCH_ID override)

  4. Environment setup: Sets KBC_BRANCH_ID for non-production branches

  5. CLI execution: Runs kbc command with the prepared environment

This ensures that when you're on feature/auth git branch mapped to Keboola branch 972851, all CLI operations target that specific development branch.

License

MIT

Available Tools

6 tools
get_mappingA

Gets the Keboola branch mapping for the current git branch.

This is a safe, read-only operation that always succeeds.

Returns: Dictionary with git_branch, keboola_branch_id, linked, and is_production

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Despite no annotations, the description discloses safe, read-only behavior and guaranteed success, which provides good transparency for a zero-parameter tool. It does not detail edge cases but is sufficient given the tool's simplicity.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: two sentences plus a bullet-like return value listing. Every sentence adds value, and the structure is front-loaded with the core action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters and an output schema present, the description covers the tool's purpose, safety, and return fields (git_branch, keboola_branch_id, linked, is_production). No gaps are apparent for the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has no parameters, so the description adds no parameter details beyond the schema. The baseline for zero parameters is 4, and the description adequately focuses on the tool's action and return value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves the Keboola branch mapping for the current git branch. It uses specific verbs and resource naming, and the purpose is distinct from sibling tools like list_mappings or link_branch.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly notes it is a safe, read-only operation that always succeeds, guiding appropriate use. However, it does not contrast with alternatives like list_mappings or provide when-not-to-use scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

kbcA

Execute a Keboola CLI command with automatic branch context.

The current git branch is automatically resolved to its mapped Keboola branch, and the KBC_BRANCH_ID environment variable is set accordingly.

ParametersJSON Schema
NameRequiredDescriptionDefault
argsNoOptional command arguments as key-value pairs Example: {"dry_run": true, "force": true, "table": "in.c-main.users"}
commandYesThe kbc command to run (e.g., 'sync push', 'remote table preview')

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It only mentions automatic branch resolution and setting KBC_BRANCH_ID, but does not disclose potential destructive actions, side effects, or requirements. The tool could run any command, including write operations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with purpose, no wasted words. Efficient and clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With full schema coverage and output schema present, the description covers the basic purpose and branch context. However, it lacks behavioral information about what commands are safe, potential side effects, or error conditions, which is important for a general CLI executor.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Both parameters are described in the schema (100% coverage). The description adds value by explaining branch context but does not enhance parameter semantics beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool executes a Keboola CLI command with automatic branch context. It uses a specific verb ('execute') and resource ('CLI command'), and distinguishes from siblings which are about mappings, branches, and docs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies this is the general CLI executor, but provides no explicit guidance on when to use it versus alternatives. It does not mention when not to use or suggest other tools for specific tasks.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_mappingsA

Lists all git-to-Keboola branch mappings.

Returns: Dictionary with mappings dict and current_git_branch

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries burden. It states the operation is a list (presumably read-only) and mentions return structure, but lacks disclosure of side effects, authentication, or system impact.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise at two sentences, front-loading the purpose and including return structure. No unnecessary information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters and presence of output schema, the description effectively explains return structure ('Dictionary with mappings dict and current_git_branch'), making it reasonably complete for a simple list tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, so schema coverage is 100% and description adds no param info. Baseline of 4 is appropriate for zero-parameter tools.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool 'Lists all git-to-Keboola branch mappings' with a specific verb and resource. It implicitly distinguishes from sibling 'get_mapping' which likely retrieves a single mapping.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this vs alternatives, but the purpose is straightforward. The sibling 'get_mapping' suggests this is for listing all mappings, implying usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_cli_docsA

Search Keboola CLI documentation for commands, flags, environment variables, and workflows.

Use this to find information about kbc commands like sync, push, pull, remote, local, branch management, environment variables (KBC_BRANCH_ID, KBC_STORAGE_API_TOKEN), and DevOps workflows.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesSearch query (e.g., 'how to push changes', 'branch environment variables', 'sync init flags')

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description carries full burden. It states the tool searches documentation but does not disclose behavioral traits like read-only nature, rate limits, or output format. It adds minimal transparency beyond the obvious search operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences: first states purpose, second gives usage guidance and examples. Every sentence is informative with no fluff. Structure is front-loaded and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has an output schema (not shown), the description need not explain return values. It adequately covers the search functionality and query examples. Could be slightly enhanced by mentioning the output type (e.g., 'returns documentation snippets'), but overall sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with a single 'query' parameter. The description adds value by providing specific examples of useful queries (e.g., 'how to push changes', 'branch environment variables'), which enriches the schema's basic description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool searches Keboola CLI documentation for commands, flags, environment variables, and workflows. It provides concrete examples (sync, push, pull, etc.), making the purpose specific and differentiated from sibling tools which deal with mappings and branches.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description says 'Use this to find information about kbc commands...' and gives examples, providing clear context for when to use the tool. However, it does not explicitly mention when not to use it or list alternatives, though sibling tools are unrelated to documentation search.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 6 tool updatesv0.1.0
    • First observedget_mapping
    • First observedkbc
    • First observedlink_branch
    • First observedlist_mappings
    • First observedsearch_cli_docs
    • First observedunlink_branch
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0
Disambiguation5/5

All six tools have distinct purposes: getting a single mapping, listing all mappings, linking, unlinking, executing CLI commands, and searching documentation. There is no overlap or ambiguity.

Naming Consistency4/5

Five tools follow a clear verb_noun pattern (get_mapping, link_branch, list_mappings, unlink_branch, search_cli_docs), but 'kbc' deviates as a short acronym, breaking the pattern slightly.

Tool Count5/5

Six tools is well-scoped for managing branch mappings and CLI execution. Each tool serves a necessary function without being excessive or sparse.

Completeness4/5

The set covers the core lifecycle of branch mappings (create via link, read via get_mapping and list_mappings, delete via unlink) and includes CLI execution and docs search. An explicit update tool is missing, but linking may also update.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/davidesner/keboola-cli-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server