Keboola MCP Server

Um servidor MCP para interagir com a plataforma de dados Keboola Connection.

Documentação

Ask DeepWiki

Keboola MCP Server

Conecte seus agentes de IA, clientes MCP (Cursor, Claude, Windsurf, VS Code ...) e outros assistentes de IA ao Keboola. Exponha dados, transformações, consultas SQL e gatilhos de jobs—sem necessidade de código de integração. Entregue os dados certos aos agentes quando e onde eles precisarem.

Visão Geral

O Keboola MCP Server é uma ponte de código aberto entre o seu projeto Keboola e ferramentas modernas de IA. Ele transforma recursos do Keboola—como acesso a armazenamento, transformações SQL e gatilhos de jobs—em ferramentas acionáveis para Claude, Cursor, CrewAI, LangChain, Amazon Q e outros.

Recursos

Com o Agente de IA e o MCP Server, você pode:

  • Armazenamento: Consulte tabelas diretamente e gerencie descrições de tabelas ou buckets.
  • Componentes: Crie, liste e inspecione extratores, gravadores, data apps e configurações de transformação.
  • SQL: Crie transformações SQL com linguagem natural.
  • Jobs: Execute componentes e transformações e recupere detalhes de execução de jobs.
  • Fluxos: Construa e gerencie pipelines de fluxo de trabalho usando Fluxos Condicionais e Fluxos Orquestradores.
  • Data Apps: Crie, implante e gerencie Data Apps Streamlit do Keboola exibindo suas consultas sobre dados de armazenamento.
  • Metadados: Pesquise, leia e atualize documentação do projeto e metadados de objetos usando linguagem natural.
  • Branches de Desenvolvimento: Trabalhe com segurança em branches de desenvolvimento fora da produção, onde todas as operações são limitadas ao branch selecionado.

🚀 Início Rápido: Servidor MCP Remoto (Forma Mais Fácil)

A forma mais fácil de usar o Keboola MCP Server é através do nosso Servidor MCP Remoto. Esta solução hospedada elimina a necessidade de configuração local, instalação ou preparação.

O que é o Servidor MCP Remoto?

Nosso servidor remoto é hospedado em cada stack multi-tenant do Keboola e suporta autenticação OAuth. Você pode se conectar a ele a partir de qualquer assistente de IA que suporte conexão HTTP Streamable remota e autenticação OAuth.

Como Conectar

  1. Obtenha a URL do seu servidor remoto: Navegue até as Configurações do Projeto Keboola → aba MCP Server
  2. Copie a URL do servidor: Ela será semelhante a https://mcp.<YOUR_REGION>.keboola.com/mcp
  3. Configure seu assistente de IA: Cole a URL nas configurações MCP do seu assistente de IA
  4. Autentique-se: Você será solicitado a autenticar com sua conta Keboola e selecionar seu projeto

Clientes Suportados

  • Cursor: Use o botão "Instalar no Cursor" nas configurações do MCP Server do seu projeto ou clique neste botão Install MCP Server
  • Claude Desktop: Adicione a integração via Configurações → Integrações
  • Claude Code: Instale usando claude mcp add --transport http keboola <URL> (veja abaixo para detalhes)
  • Windsurf: Configure com a URL do servidor remoto
  • Make: Configure com a URL do servidor remoto
  • Outros clientes MCP: Configure com a URL do servidor remoto

Configuração do Claude Code

O Claude Code é uma ferramenta de interface de linha de comando que permite interagir com o Claude usando seu terminal. Você pode instalar a integração do Keboola MCP Server usando um comando simples.

Instalação:

Execute o seguinte comando no seu terminal, substituindo <YOUR_REGION> pela sua região Keboola:

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

Comandos específicos por região:

RegiãoComando de Instalação
US Virginia AWSclaude mcp add --transport http keboola https://mcp.keboola.com/mcp
US Virginia GCPclaude mcp add --transport http keboola https://mcp.us-east4.gcp.keboola.com/mcp
EU Frankfurt AWSclaude mcp add --transport http keboola https://mcp.eu-central-1.keboola.com/mcp
EU Ireland Azureclaude mcp add --transport http keboola https://mcp.north-europe.azure.keboola.com/mcp
EU Frankfurt GCPclaude mcp add --transport http keboola https://mcp.europe-west3.gcp.keboola.com/mcp

Uso:

Após a instalação, você pode usar o Keboola MCP Server no Claude Code digitando /mcp na sua conversa e selecionando as ferramentas Keboola que deseja usar.

Autenticação:

Ao usar o Keboola MCP Server no Claude Code pela primeira vez, uma janela do navegador será aberta solicitando que você:

  1. Faça login com sua conta Keboola
  2. Selecione o projeto ao qual deseja se conectar
  3. Autorize a conexão

Após a autenticação, você pode começar a usar as ferramentas Keboola diretamente do Claude Code.

Para instruções detalhadas de configuração e URLs específicas por região, consulte nossa documentação de configuração do servidor remoto.

Usando Branches de Desenvolvimento

Você pode trabalhar com segurança em branches de desenvolvimento do Keboola sem afetar seus dados de produção. Os servidores MCP hospedados remotamente respeitam o parâmetro KBC_BRANCH_ID e limitam todas as operações ao branch especificado. Você pode encontrar o ID do branch de desenvolvimento na URL ao navegar para o branch de desenvolvimento na interface, por exemplo: https://connection.us-east4.gcp.keboola.com/admin/projects/PROJECT_ID/branch/BRANCH_ID/dashboard. O ID do branch deve ser incluído em cada solicitação usando o cabeçalho X-Branch-Id: <branchId>, caso contrário, o MCP Server usa o branch de produção por padrão. Isso deve ser gerenciado pelo cliente de IA ou pelo ambiente que lida com a conexão do servidor.

Autorização de Ferramentas e Controle de Acesso

Ao usar transportes baseados em HTTP (Streamable HTTP), você pode controlar quais ferramentas estão disponíveis para os clientes usando cabeçalhos HTTP. Isso é útil para restringir as capacidades dos agentes de IA ou impor políticas de conformidade.

Cabeçalhos de Autorização

CabeçalhoDescriçãoExemplo
X-Allowed-ToolsLista separada por vírgulas de ferramentas permitidasget_configs,get_buckets,query_data
X-Disallowed-ToolsLista separada por vírgulas de ferramentas a excluircreate_config,run_job
X-Read-Only-ModeRestringir apenas a ferramentas somente leituratrue, 1, ou yes

Comportamento do Filtro

Os filtros são aplicados em ordem: permitido → interseção somente leitura → exclusão não permitida. Cabeçalhos vazios = sem restrição.

Ferramentas Somente Leitura

Ferramentas somente leitura são aquelas anotadas com readOnlyHint=True. Essas ferramentas apenas recuperam informações sem fazer alterações no seu projeto Keboola. Para a lista atual de ferramentas somente leitura, consulte o arquivo TOOLS.md, que é um instantâneo gerado automaticamente do conjunto real de ferramentas.

Exemplo: Acesso Somente Leitura

X-Read-Only-Mode: true

Para documentação detalhada, consulte developers.keboola.com/integrate/mcp/#tool-authorization-and-access-control.


Configuração Local do MCP Server (Forma Personalizada ou de Desenvolvimento)

Execute o servidor MCP na sua própria máquina para controle total e desenvolvimento fácil. Escolha esta opção quando quiser personalizar ferramentas, depurar localmente ou iterar rapidamente. Você clonará o repositório, definirá as credenciais do Keboola por meio de variáveis de ambiente ou cabeçalhos, dependendo do transporte do servidor, instalará as dependências e iniciará o servidor. Essa abordagem oferece máxima flexibilidade (ferramentas personalizadas, registro local, iteração offline), mas requer configuração manual e você gerencia atualizações e segredos por conta própria.

O servidor suporta várias opções de transporte, que podem ser selecionadas fornecendo o argumento --transport <transport> ao iniciar o servidor:

  • stdio - Padrão quando --transport não é especificado. Entrada/saída padrão, normalmente usado para implantação local com um único cliente.
  • streamable-http - Executa o servidor remotamente via HTTP com um canal de streaming bidirecional, permitindo que o cliente e o servidor troquem mensagens continuamente. Conecte-se via /mcp (por exemplo, http://localhost:8000/mcp).
  • http-compat - Um alias para streamable-http, mantido para compatibilidade retroativa.

Para a comunicação cliente-servidor, as credenciais do Keboola devem ser fornecidas para permitir o trabalho com seu projeto na sua Região Keboola. Os seguintes são necessários: KBC_STORAGE_TOKEN, KBC_STORAGE_API_URL, KBC_WORKSPACE_SCHEMA e opcionalmente KBC_BRANCH_ID. Você pode fornecê-los de duas maneiras:

  • Para uso pessoal (principalmente com transporte stdio): defina as variáveis de ambiente antes de iniciar o servidor. Todas as solicitações reutilizarão essas credenciais predefinidas.
  • Para uso multiusuário: inclua as variáveis nos cabeçalhos das solicitações para que cada solicitação use as credenciais fornecidas com ela.

Duas das variáveis não são obtidas dos cabeçalhos das solicitações:

  • KBC_STORAGE_API_URL: um servidor que foi iniciado com sua própria URL da Storage API (o parâmetro --api-url ou a variável de ambiente KBC_STORAGE_API_URL) atende apenas a esse stack do Keboola. Um cabeçalho X-Storage-Api-Url solicitando um host diferente é ignorado (um aviso é registrado) — o servidor mantém sua própria URL para a solicitação. Inicie o servidor sem uma URL da Storage API própria se quiser que cada solicitação escolha seu stack.
  • KBC_KUBERNETES_TOKEN_PATH (apenas servidores implantados, consulte docs/kubernetes-sa-auth.md): lido apenas do ambiente, nunca de um cabeçalho.

KBC_STORAGE_TOKEN

Este é o seu token de autenticação para o Keboola:

Para instruções sobre como criar e gerenciar tokens da Storage API, consulte a documentação oficial do Keboola.

Nota: Se você quiser que o servidor MCP tenha acesso limitado, use um token de armazenamento personalizado; se quiser que o MCP acesse tudo no seu projeto, use o token mestre.

KBC_WORKSPACE_SCHEMA

Isso identifica seu workspace no Keboola e é usado para consultas SQL. No entanto, isso é necessário apenas se você estiver usando um token de armazenamento personalizado em vez do Token Mestre:

Nota: Ao criar um workspace manualmente, marque a opção Conceder acesso somente leitura a todos os dados do Projeto

Nota: KBC_WORKSPACE_SCHEMA é chamado de Nome do Dataset em workspaces do BigQuery; basta clicar em conectar e copiar o Nome do Dataset

KBC_STORAGE_API_URL (Região Keboola)

A URL da API da sua Região Keboola depende da sua região de implantação. Você pode determinar sua região observando a URL no seu navegador quando estiver logado no seu projeto Keboola:

RegiãoURL da API
AWS North Americahttps://connection.keboola.com
AWS Europehttps://connection.eu-central-1.keboola.com
Google Cloud EUhttps://connection.europe-west3.gcp.keboola.com
Google Cloud UShttps://connection.us-east4.gcp.keboola.com
Azure EUhttps://connection.north-europe.azure.keboola.com

KBC_BRANCH_ID (Opcional)

Para operar em um branch de desenvolvimento do Keboola específico, defina o ID do branch usando o parâmetro KBC_BRANCH_ID. O servidor MCP limita sua funcionalidade ao branch especificado, garantindo que todas as alterações permaneçam isoladas e não impactem o branch de produção.

  • Se não for fornecido, o servidor usa o branch de produção por padrão.
  • Para trabalho de desenvolvimento, defina KBC_BRANCH_ID para o ID numérico do seu branch (por exemplo, 123456). Você pode encontrar o ID do branch de desenvolvimento na URL ao navegar para o branch de desenvolvimento na interface, por exemplo: https://connection.us-east4.gcp.keboola.com/admin/projects/PROJECT_ID/branch/BRANCH_ID/dashboard.
  • Em transportes remotos, você pode substituir por solicitação com o cabeçalho HTTP X-Branch-Id: <branchId> ou KBC_BRANCH_ID: <branchId>.

Instalação

Certifique-se de ter:

  • Python 3.10+ instalado
  • Acesso a um projeto Keboola com direitos de administrador
  • Seu cliente MCP preferido (Claude, Cursor, etc.)

Nota: Certifique-se de ter o uv instalado. O cliente MCP o usará para baixar e executar automaticamente o Keboola MCP Server.

Instalando o uv:

macOS/Linux:

#if homebrew is not installed on your machine use:
# /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install using Homebrew
brew install uv

Windows:

# Using the installer script
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or using pip
pip install uv

# Or using winget
winget install --id=astral-sh.uv -e

Para mais opções de instalação, consulte a documentação oficial do uv.

Executando o Keboola MCP Server

Existem quatro maneiras de usar o Keboola MCP Server, dependendo das suas necessidades:

Opção A: Modo Integrado (Recomendado)

Neste modo, o Claude ou o Cursor inicia automaticamente o servidor MCP para você. Você não precisa executar nenhum comando no seu terminal.

  1. Configure seu cliente MCP (Claude/Cursor) com as configurações apropriadas
  2. O cliente iniciará automaticamente o servidor MCP quando necessário

Configuração do Claude Desktop

  1. Vá para Claude (canto superior esquerdo da tela) -> Configurações → Desenvolvedor → Editar Config (se você não vir o claude_desktop_config.json, crie-o)
  2. Adicione a seguinte configuração:
  3. Reinicie o Claude desktop para que as alterações tenham efeito
{
  "mcpServers": {
    "keboola": {
      "command": "uvx",
      "args": ["keboola_mcp_server --transport <transport>"],
      "env": {
        "KBC_STORAGE_API_URL": "https://connection.YOUR_REGION.keboola.com",
        "KBC_STORAGE_TOKEN": "your_keboola_storage_token",
        "KBC_WORKSPACE_SCHEMA": "your_workspace_schema",
        "KBC_BRANCH_ID": "your_branch_id_optional"
      }
    }
  }
}

Locais do arquivo de configuração:

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

Configuração do Cursor

  1. Vá para Configurações → MCP
  2. Clique em "+ Adicionar novo servidor MCP global"
  3. Configure com estas configurações:
{
  "mcpServers": {
    "keboola": {
      "command": "uvx",
      "args": ["keboola_mcp_server --transport <transport>"],
      "env": {
        "KBC_STORAGE_API_URL": "https://connection.YOUR_REGION.keboola.com",
        "KBC_STORAGE_TOKEN": "your_keboola_storage_token",
        "KBC_WORKSPACE_SCHEMA": "your_workspace_schema",
        "KBC_BRANCH_ID": "your_branch_id_optional"
      }
    }
  }
}

Nota: Use nomes curtos e descritivos para servidores MCP. Como o nome completo da ferramenta inclui o nome do servidor e deve permanecer abaixo de ~60 caracteres, nomes mais longos podem ser filtrados no Cursor e não serão exibidos ao Agente.

Configuração do Cursor para Windows WSL

Ao executar o servidor MCP do Subsistema Windows para Linux com o Cursor AI, use esta configuração:

{
  "mcpServers": {
    "keboola":{
      "command": "wsl.exe",
      "args": [
          "bash",
          "-c '",
          "export KBC_STORAGE_API_URL=https://connection.YOUR_REGION.keboola.com &&",
          "export KBC_STORAGE_TOKEN=your_keboola_storage_token &&",
          "export KBC_WORKSPACE_SCHEMA=your_workspace_schema &&",
          "export KBC_BRANCH_ID=your_branch_id_optional &&",
          "/snap/bin/uvx keboola_mcp_server --transport <transport>",
          "'"
      ]
    }
  }
}

Opção B: Modo de Desenvolvimento Local

Para desenvolvedores que trabalham no código do servidor MCP:

  1. Clone o repositório e configure um ambiente local
  2. Configure o Claude/Cursor para usar seu caminho Python local:
{
  "mcpServers": {
    "keboola": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": [
        "-m",
        "keboola_mcp_server --transport <transport>"
      ],
      "env": {
        "KBC_STORAGE_API_URL": "https://connection.YOUR_REGION.keboola.com",
        "KBC_STORAGE_TOKEN": "your_keboola_storage_token",
        "KBC_WORKSPACE_SCHEMA": "your_workspace_schema",
        "KBC_BRANCH_ID": "your_branch_id_optional"
      }
    }
  }
}

Opção C: Modo CLI Manual (Somente para Testes)

Você pode executar o servidor manualmente em um terminal para testes ou depuração:

# Set environment variables
export KBC_STORAGE_API_URL=https://connection.YOUR_REGION.keboola.com
export KBC_STORAGE_TOKEN=your_keboola_storage_token
export KBC_WORKSPACE_SCHEMA=your_workspace_schema
export KBC_BRANCH_ID=your_branch_id_optional

uvx keboola_mcp_server --transport streamable-http

Nota: Este modo é principalmente para depuração ou testes. Para uso normal com Claude ou Cursor, você não precisa executar o servidor manualmente.

Nota: O servidor usará o transporte HTTP Streamable e escutará em localhost:8000 para conexões de entrada em /mcp. Você pode usar os parâmetros --port e --host para fazê-lo escutar em outro lugar.

Opção D: Usando Docker

docker pull keboola/mcp-server:latest

docker run \
  --name keboola_mcp_server \
  --rm \
  -it \
  -p 127.0.0.1:8000:8000 \
  -e KBC_STORAGE_API_URL="https://connection.YOUR_REGION.keboola.com" \
  -e KBC_STORAGE_TOKEN="YOUR_KEBOOLA_STORAGE_TOKEN" \
  -e KBC_WORKSPACE_SCHEMA="YOUR_WORKSPACE_SCHEMA" \
  -e KBC_BRANCH_ID="YOUR_BRANCH_ID_OPTIONAL" \
  keboola/mcp-server:latest \
  --transport streamable-http \
  --host 0.0.0.0

Nota: O servidor usará o transporte HTTP Streamable e escutará em localhost:8000 para conexões de entrada em /mcp. Você pode alterar -p para mapear a porta do contêiner para outro lugar.

Preciso Iniciar o Servidor Eu Mesmo?

CenárioPrecisa Executar Manualmente?Use Esta Configuração
Usando Claude/CursorNãoConfigure MCP nas configurações do aplicativo
Desenvolvendo MCP localmenteNão (Claude o inicia)Aponte a configuração para o caminho do python
Testando CLI manualmenteSimUse o terminal para executar
Usando DockerSimExecute o contêiner docker

Usando o Servidor MCP

Depois que seu cliente MCP (Claude/Cursor) estiver configurado e em execução, você pode começar a consultar seus dados do Keboola:

Verifique Sua Configuração

Você pode começar com uma consulta simples para confirmar que tudo está funcionando:

What buckets and tables are in my Keboola project?

Exemplos do Que Você Pode Fazer

Exploração de Dados:

  • "Quais tabelas contêm informações de clientes?"
  • "Execute uma consulta para encontrar os 10 principais clientes por receita"

Análise de Dados:

  • "Analise meus dados de vendas por região no último trimestre"
  • "Encontre correlações entre idade do cliente e frequência de compra"

Pipelines de Dados:

  • "Crie uma transformação SQL que una as tabelas de clientes e pedidos"
  • "Inicie o trabalho de extração de dados para meu componente Salesforce"

Compatibilidade

Suporte a Clientes MCP

Cliente MCPStatus de SuporteMétodo de Conexão
Claude (Desktop e Web)✅ suportadostdio
Cursor✅ suportadostdio
Windsurf, Zed, Replit✅ Suportadostdio
Codeium, Sourcegraph✅ SuportadoHTTP Streamable
Clientes MCP personalizados✅ SuportadoHTTP Streamable ou stdio

Ferramentas Suportadas

Nota: Seus agentes de IA se ajustarão automaticamente a novas ferramentas.

Para uma lista completa de ferramentas disponíveis com descrições detalhadas, parâmetros e exemplos de uso, consulte TOOLS.md.

Solução de Problemas

Problemas Comuns

ProblemaSolução
Erros de AutenticaçãoVerifique se KBC_STORAGE_TOKEN é válido
Problemas de WorkspaceConfirme se KBC_WORKSPACE_SCHEMA está correto
Tempo de Conexão EsgotadoVerifique a conectividade de rede

Desenvolvimento

Instalação

Configuração básica:

uv sync --extra dev

Com a configuração básica, você pode usar uv run tox para executar testes e verificar o estilo do código.

Configuração recomendada:

uv sync --extra dev --extra tests --extra integtests --extra codestyle

Com a configuração recomendada, pacotes para testes e verificação de estilo de código serão instalados, o que permite que IDEs como VsCode ou Cursor verifiquem o código ou executem testes durante o desenvolvimento.

Testes de integração

Para executar testes de integração localmente, use uv run tox -e integtests. NOTA: Você precisará definir as seguintes variáveis de ambiente:

  • INTEGTEST_POOL_STORAGE_API_URL
  • INTEGTEST_STORAGE_TOKENS
  • INTEGTEST_STORAGE_TOKEN_STORAGE_BRANCHES

Para obter esses valores, você precisa de projetos Keboola dedicados para testes de integração. Cada sessão de teste cria seu próprio workspace somente leitura, portanto, nenhum esquema de workspace precisa ser configurado. Consulte integtests/README.md para instruções detalhadas de configuração e documentação de design.

Atualizando uv.lock

Atualize o arquivo uv.lock se você adicionou ou removeu dependências. Considere também atualizar o lock com versões mais recentes de dependências ao criar um release (uv lock --upgrade).

Atualizando a Documentação de Ferramentas

Quando você fizer alterações em qualquer descrição de ferramenta (docstrings em funções de ferramenta), você deve regenerar o arquivo de documentação TOOLS.md para refletir essas alterações:

uv run python -m src.keboola_mcp_server.generate_tool_docs

Lançamento (Release)

Nós não fazemos um release para cada PR mesclado. O trabalho chega ao trunk (main) continuamente, e lançamos periodicamente depois que as alterações são re-testadas juntas — isso evita quebrar configurações funcionais para os usuários.

Um release é feito enviando uma ou duas tags git:

  • vX.Y.Z — o release do servidor MCP (sempre)
  • agent-vX.Y.Z — o release do Agente na Plataforma (somente quando o agente também está sendo lançado)

Qualquer tag aciona o CI release.yml, que compila e publica a imagem Docker. O KaiBench é executado apenas em tags de produção vX.Y.Z (não em agent-vX.Y.Z, nem em pré-lançamentos -dev.). Use a skill release-notes — ela prepara as notas de release e o PR de rascunho e orienta sobre a marcação de vX.Y.Z e agent-vX.Y.Z.

Suporte e Feedback

⭐ A principal forma de obter ajuda, relatar bugs ou solicitar recursos é abrindo uma issue no GitHub. ⭐

A equipe de desenvolvimento monitora ativamente as issues e responderá o mais rápido possível. Para informações gerais sobre Keboola, use os recursos abaixo.

Recursos

Conectar