Keboola MCP Server
Um servidor MCP para interagir com a plataforma de dados Keboola Connection.
Documentação
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
- Obtenha a URL do seu servidor remoto: Navegue até as Configurações do Projeto Keboola → aba
MCP Server - Copie a URL do servidor: Ela será semelhante a
https://mcp.<YOUR_REGION>.keboola.com/mcp - Configure seu assistente de IA: Cole a URL nas configurações MCP do seu assistente de IA
- 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
- 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ã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 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ê:
- Faça login com sua conta Keboola
- Selecione o projeto ao qual deseja se conectar
- 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ç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: 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--transportnã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 parastreamable-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-urlou a variável de ambienteKBC_STORAGE_API_URL) atende apenas a esse stack do Keboola. Um cabeçalhoX-Storage-Api-Urlsolicitando 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:
- 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 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ão | URL da API |
|---|---|
| AWS North America | https://connection.keboola.com |
| AWS Europe | https://connection.eu-central-1.keboola.com |
| Google Cloud EU | https://connection.europe-west3.gcp.keboola.com |
| Google Cloud US | https://connection.us-east4.gcp.keboola.com |
| Azure EU | https://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_IDpara 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>ouKBC_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.
- Configure seu cliente MCP (Claude/Cursor) com as configurações apropriadas
- O cliente iniciará automaticamente o servidor MCP quando necessário
Configuração do Claude Desktop
- 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)
- Adicione a seguinte configuração:
- 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
- Vá para Configurações → MCP
- Clique em "+ Adicionar novo servidor MCP global"
- 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:
- Clone o repositório e configure um ambiente local
- 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:8000para conexões de entrada em/mcp. Você pode usar os parâmetros--porte--hostpara 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:8000para conexões de entrada em/mcp. Você pode alterar-ppara mapear a porta do contêiner para outro lugar.
Preciso Iniciar o Servidor Eu Mesmo?
| Cenário | Precisa Executar Manualmente? | Use Esta Configuração |
|---|---|---|
| Usando Claude/Cursor | Não | Configure MCP nas configurações do aplicativo |
| Desenvolvendo MCP localmente | Não (Claude o 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
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 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 | HTTP Streamable |
| Clientes MCP personalizados | ✅ Suportado | HTTP 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
| 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 Esgotado | 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, 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_URLINTEGTEST_STORAGE_TOKENSINTEGTEST_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
- Documentação do Usuário
- Documentação do Desenvolvedor
- Plataforma Keboola
- Rastreador de Issues ← Método de contato principal para o Servidor MCP