Keboola Cli 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

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

   • Install from: https://developers.keboola.com/cli/

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