┌─────────────────────────────────────────────────────────────────────┐
│                         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                                      │
└─────────────────────────────────────────────────────────────────────┘

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

# 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

{
  "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"
      }
    }
  }
}

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

{
  "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"
      }
    }
  }
}

{
  "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"
      }
    }
  }
}

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": "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"
}

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

{
  "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"]
}

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

# Or use the entry point
keboola-cli-mcp

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

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

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