Keboola

Servidor MCP Keboola

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 cola. Entregue os dados certos aos agentes quando e onde eles precisarem.

Visão Geral

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

• Início Rápido
• Configuração Local

Recursos

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

• Armazenamento: Consultar tabelas diretamente e gerenciar descrições de tabelas ou buckets
• Componentes: Criar, listar e inspecionar extratores, gravadores, data apps e configurações de transformação
• SQL: Criar transformações SQL com linguagem natural
• Jobs: Executar componentes e transformações, e recuperar detalhes de execução de jobs
• Fluxos: Construir e gerenciar pipelines de workflow usando Fluxos Condicionais e Fluxos Orquestradores.
• Data Apps: Criar, implantar e gerenciar Data Apps Keboola Streamlit exibindo suas consultas sobre dados de armazenamento.
• Metadados: Pesquisar, ler e atualizar 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 Servidor MCP Keboola é através do nosso Servidor MCP Remoto. Esta solução hospedada elimina a necessidade de configuração local, ajustes ou instalação.

O que é o Servidor MCP Remoto?

Nosso servidor remoto é hospedado em todos os stacks 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é Configurações do Projeto Keboola → aba MCP Server
2. Copie a URL do servidor: Ela parecerá com 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: 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 Servidor MCP do seu projeto ou clique neste botão
• 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 Servidor MCP Keboola 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ão	Comando de Instalação
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

Uso:

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

Autenticação:

Quando você usar o Servidor MCP Keboola no Claude Code pela primeira vez, uma janela do navegador abrirá 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 limitarão 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 requisição usando o cabeçalho X-Branch-Id: <branchId>; caso contrário, o Servidor MCP usa o branch de produção como padrão. Isso deve ser gerenciado pelo cliente de IA ou pelo ambiente que gerencia a conexão do servidor.

Autorização de Ferramentas e Controle de Acesso

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

Cabeçalhos de Autorização

Cabeçalho	Descrição	Exemplo
X-Allowed-Tools	Lista separada por vírgulas de ferramentas permitidas	get_configs,get_buckets,query_data
X-Disallowed-Tools	Lista separada por vírgulas de ferramentas a excluir	create_config,run_job
X-Read-Only-Mode	Restringir apenas a ferramentas somente leitura	true, 1 ou yes

Comportamento do Filtro

Os filtros são aplicados em ordem: permitidas → interseção somente leitura → exclusão de não permitidas. 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 snapshot 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 Servidor MCP (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 Keboola via variáveis de ambiente ou cabeçalhos, dependendo do transporte do servidor, instalará as dependências e iniciará o servidor. Esta abordagem oferece máxima flexibilidade (ferramentas personalizadas, logs locais, iteração offline), mas requer configuração manual e você gerencia atualizações e segredos por conta própria.

O servidor suporta múltiplas 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, tipicamente 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 cliente e servidor troquem mensagens continuamente. Conecte via /mcp (ex.: http://localhost:8000/mcp).
• http-compat - Um alias para streamable-http, mantido para compatibilidade retroativa.

Para comunicação cliente–servidor, as credenciais Keboola devem ser fornecidas para permitir trabalhar 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 formas:

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

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

• KBC_STORAGE_API_URL: um servidor iniciado com sua própria URL de API de Armazenamento (o parâmetro --api-url ou a variável de ambiente KBC_STORAGE_API_URL) atende apenas a esse stack Keboola. Um cabeçalho X-Storage-Api-Url solicitando um host diferente é ignorado (um aviso é registrado no log) — o servidor mantém sua própria URL para a requisição. Inicie o servidor sem uma URL de API de Armazenamento própria se quiser que cada requisiçã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 é seu token de autenticação para o Keboola:

Para instruções sobre como criar e gerenciar tokens da API de Armazenamento, 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 é apenas necessário se você estiver usando um token de armazenamento personalizado em vez do Token Mestre:

• Se estiver usando Token Mestre: O workspace é criado automaticamente nos bastidores
• Se estiver usando token de armazenamento personalizado: Siga este guia do Keboola para obter seu KBC_WORKSPACE_SCHEMA

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 BigQuery; você simplesmente clica em conectar e copia 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ão	URL da API
AWS América do Norte	https://connection.keboola.com
AWS Europa	https://connection.eu-central-1.keboola.com
Google Cloud UE	https://connection.europe-west3.gcp.keboola.com
Google Cloud EUA	https://connection.us-east4.gcp.keboola.com
Azure UE	https://connection.north-europe.azure.keboola.com

KBC_BRANCH_ID (Opcional)

Para operar em um branch de desenvolvimento específico do Keboola, 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 (ex.: 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 requisiçã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 uv instalado. O cliente MCP o usará para baixar e executar automaticamente o Servidor MCP Keboola. Instalando 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 Servidor MCP Keboola

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

Opção A: Modo Integrado (Recomendado)

Neste modo, o Claude ou o Cursor iniciam 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 sua 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 MCP Server global”
3. Configure com estas definiçõ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 a partir 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 próprio código do servidor MCP:

1. Clone o repositório e configure um ambiente local
2. Configure o Claude/Cursor para usar o 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 Streamable HTTP 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 Streamable HTTP 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.

Eu Preciso Iniciar o Servidor Eu Mesmo?

Cenário	Necessário Executar Manualmente?	Use Esta Configuração
Usando Claude/Cursor	Não	Configure o MCP nas configurações do aplicativo
Desenvolvendo MCP localmente	Não (o Claude inicia)	Aponte a configuração para o caminho do python
Testando CLI manualmente	Sim	Use o terminal para executar
Usando Docker	Sim	Execute o contêiner docker

Usando o Servidor MCP

Quando 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 junte as tabelas de clientes e pedidos”
• “Inicie o trabalho de extração de dados para o meu componente Salesforce”

Compatibilidade

Suporte a Clientes MCP

Cliente MCP	Status de Suporte	Método de Conexão
Claude (Desktop e Web)	✅ suportado	stdio
Cursor	✅ suportado	stdio
Windsurf, Zed, Replit	✅ suportado	stdio
Codeium, Sourcegraph	✅ suportado	Streamable HTTP
Clientes MCP Personalizados	✅ suportado	Streamable HTTP 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

Problema	Solução
Erros de Autenticação	Verifique se KBC_STORAGE_TOKEN é válido
Problemas de Workspace	Confirme se KBC_WORKSPACE_SCHEMA está correto
Tempo de Conexão Excedido	Verifique 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, os pacotes para testes e verificação de estilo de código serão instalados, permitindo 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 schema 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 novas de dependências ao criar um release (uv lock --upgrade).

Atualizando a Documentação das Ferramentas

Quando você faz alterações nas descrições de qualquer ferramenta (docstrings nas funções da 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 cortamos um release para cada PR mesclado. O trabalho chega ao trunk (main) continuamente, e lançamos periodicamente uma vez que as alterações foram retestadas em conjunto — isso evita quebrar configurações de trabalho para os usuários.

Um release é feito empurrando uma ou duas git tags:

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

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

Suporte e Feedback

⭐ A principal maneira 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

• Documentação do Usuário
• Documentação do Desenvolvedor
• Plataforma Keboola
• Rastreador de Issues ← Método de contato principal para o Servidor MCP

Conecte-se

• LinkedIn
• Twitter
• Changelog