Keboola MCP Server

oficial

Construye flujos de datos robustos, integraciones y análisis en una única plataforma intuitiva.

Documentación

Ask DeepWiki

Servidor MCP de Keboola

Conecta tus agentes de IA, clientes MCP (Cursor, Claude, Windsurf, VS Code ...) y otros asistentes de IA a Keboola. Expón datos, transformaciones, consultas SQL y disparadores de trabajos—sin necesidad de código adicional. Entrega los datos correctos a los agentes cuando y donde los necesiten.

Descripción general

El Servidor MCP de Keboola es un puente de código abierto entre tu proyecto de Keboola y las herramientas modernas de IA. Convierte las funcionalidades de Keboola—como el acceso al almacenamiento, las transformaciones SQL y los disparadores de trabajos—en herramientas invocables para Claude, Cursor, CrewAI, LangChain, Amazon Q y más.

Funcionalidades

Con el Agente de IA y el Servidor MCP, puedes:

  • Almacenamiento: Consultar tablas directamente y gestionar descripciones de tablas o buckets
  • Componentes: Crear, listar e inspeccionar extractores, escritores, aplicaciones de datos y configuraciones de transformación
  • SQL: Crear transformaciones SQL con lenguaje natural
  • Trabajos: Ejecutar componentes y transformaciones, y recuperar detalles de ejecución de trabajos
  • Flujos: Construir y gestionar flujos de trabajo usando Flujos Condicionales y Flujos de Orquestador.
  • Aplicaciones de datos: Crear, desplegar y gestionar Aplicaciones de Datos Streamlit de Keboola que muestren tus consultas sobre los datos del almacenamiento.
  • Metadatos: Buscar, leer y actualizar la documentación del proyecto y los metadatos de los objetos usando lenguaje natural
  • Ramas de desarrollo: Trabaja de forma segura en ramas de desarrollo fuera de producción, donde todas las operaciones se limitan a la rama seleccionada.

🚀 Inicio rápido: Servidor MCP Remoto (La forma más fácil)

La forma más fácil de usar el Servidor MCP de Keboola es a través de nuestro Servidor MCP Remoto. Esta solución alojada elimina la necesidad de configuración local o instalación.

¿Qué es el Servidor MCP Remoto?

Nuestro servidor remoto está alojado en cada stack multi-tenant de Keboola y soporta autenticación OAuth. Puedes conectarte a él desde cualquier asistente de IA que soporte conexión HTTP Transmisible Remota y autenticación OAuth.

Cómo conectarse

  1. Obtén la URL de tu servidor remoto: Navega a Configuración del Proyecto Keboola → pestaña MCP Server
  2. Copia la URL del servidor: Se verá como https://mcp.<YOUR_REGION>.keboola.com/mcp
  3. Configura tu asistente de IA: Pega la URL en la configuración MCP de tu asistente de IA
  4. Autentícate: Se te pedirá que te autentiques con tu cuenta de Keboola y selecciones tu proyecto

Clientes soportados

  • Cursor: Usa el botón "Instalar en Cursor" en la configuración del Servidor MCP de tu proyecto o haz clic en este botón Install MCP Server
  • Claude Desktop: Añade la integración a través de Configuración → Integraciones
  • Claude Code: Instala usando claude mcp add --transport http keboola <URL> (ver detalles abajo)
  • Windsurf: Configura con la URL del servidor remoto
  • Make: Configura con la URL del servidor remoto
  • Otros clientes MCP: Configura con la URL del servidor remoto

Configuración de Claude Code

Claude Code es una herramienta de interfaz de línea de comandos que te permite interactuar con Claude usando tu terminal. Puedes instalar la integración del Servidor MCP de Keboola usando un comando simple.

Instalación:

Ejecuta el siguiente comando en tu terminal, reemplazando <YOUR_REGION> con tu región de Keboola:

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

Comandos específicos por región:

RegiónComando de instalación
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:

Una vez instalado, puedes usar el Servidor MCP de Keboola en Claude Code escribiendo /mcp en tu conversación y seleccionando las herramientas de Keboola que quieras usar.

Autenticación:

Cuando uses por primera vez el Servidor MCP de Keboola en Claude Code, se abrirá una ventana del navegador pidiéndote que:

  1. Inicies sesión con tu cuenta de Keboola
  2. Selecciones el proyecto al que quieres conectarte
  3. Autorices la conexión

Después de la autenticación, puedes empezar a usar las herramientas de Keboola directamente desde Claude Code.

Para instrucciones detalladas de configuración y URLs específicas por región, consulta nuestra documentación de configuración del servidor remoto.

Uso de ramas de desarrollo

Puedes trabajar de forma segura en ramas de desarrollo de Keboola sin afectar tus datos de producción. Los servidores MCP alojados remotamente respetan el parámetro KBC_BRANCH_ID y limitarán todas las operaciones a la rama especificada. Puedes encontrar el ID de la rama de desarrollo en la URL cuando navegas a la rama de desarrollo en la interfaz de usuario, por ejemplo: https://connection.us-east4.gcp.keboola.com/admin/projects/PROJECT_ID/branch/BRANCH_ID/dashboard. El ID de la rama debe incluirse en cada solicitud usando la cabecera X-Branch-Id: <branchId>, de lo contrario, el Servidor MCP usa la rama de producción por defecto. Esto debe ser gestionado por el cliente de IA o el entorno que maneja la conexión del servidor.

Autorización de herramientas y control de acceso

Cuando uses transportes basados en HTTP (HTTP Transmisible), puedes controlar qué herramientas están disponibles para los clientes usando cabeceras HTTP. Esto es útil para restringir las capacidades del agente de IA o hacer cumplir políticas de conformidad.

Cabeceras de autorización

CabeceraDescripciónEjemplo
X-Allowed-ToolsLista separada por comas de herramientas permitidasget_configs,get_buckets,query_data
X-Disallowed-ToolsLista separada por comas de herramientas a excluircreate_config,run_job
X-Read-Only-ModeRestringir solo a herramientas de solo lecturatrue, 1, o yes

Comportamiento del filtro

Los filtros se aplican en orden: permitidas → intersección de solo lectura → exclusión de no permitidas. Cabeceras vacías = sin restricción.

Herramientas de solo lectura

Las herramientas de solo lectura son aquellas anotadas con readOnlyHint=True. Estas herramientas solo recuperan información sin realizar cambios en tu proyecto de Keboola. Para la lista actual de herramientas de solo lectura, consulta el archivo TOOLS.md, que es una instantánea autogenerada del conjunto real de herramientas.

Ejemplo: Acceso de solo lectura

X-Read-Only-Mode: true

Para documentación detallada, consulta developers.keboola.com/integrate/mcp/#tool-authorization-and-access-control.


Configuración del Servidor MCP Local (Forma personalizada o de desarrollo)

Ejecuta el servidor MCP en tu propia máquina para tener control total y facilitar el desarrollo. Elige esta opción cuando quieras personalizar herramientas, depurar localmente o iterar rápidamente. Clonarás el repositorio, establecerás las credenciales de Keboola mediante variables de entorno o cabeceras según el transporte del servidor, instalarás las dependencias e iniciarás el servidor. Este enfoque ofrece máxima flexibilidad (herramientas personalizadas, registro local, iteración sin conexión) pero requiere configuración manual y tú gestionas las actualizaciones y los secretos.

El servidor soporta múltiples opciones de transporte, que se pueden seleccionar proporcionando el argumento --transport <transport> al iniciar el servidor:

  • stdio - Valor por defecto cuando no se especifica --transport. Entrada/salida estándar, típicamente usado para despliegue local con un solo cliente.
  • streamable-http - Ejecuta el servidor de forma remota sobre HTTP con un canal de transmisión bidireccional, permitiendo que el cliente y el servidor intercambien mensajes continuamente. Conéctate a través de /mcp (ej., http://localhost:8000/mcp).
  • http-compat - Un alias para streamable-http, mantenido por compatibilidad con versiones anteriores.

Para la comunicación cliente–servidor, se deben proporcionar las credenciales de Keboola para permitir trabajar con tu proyecto en tu Región de Keboola. Se requieren los siguientes: KBC_STORAGE_TOKEN, KBC_STORAGE_API_URL, KBC_WORKSPACE_SCHEMA y opcionalmente KBC_BRANCH_ID. Puedes proporcionarlos de dos maneras:

  • Para uso personal (principalmente con transporte stdio): establece las variables de entorno antes de iniciar el servidor. Todas las solicitudes reutilizarán estas credenciales predefinidas.
  • Para uso multiusuario: incluye las variables en las cabeceras de la solicitud para que cada solicitud use las credenciales proporcionadas con ella.

KBC_STORAGE_TOKEN

Este es tu token de autenticación para Keboola:

Para instrucciones sobre cómo crear y gestionar tokens de la API de Storage, consulta la documentación oficial de Keboola.

Nota: Si quieres que el servidor MCP tenga acceso limitado, usa un token de almacenamiento personalizado; si quieres que el MCP acceda a todo en tu proyecto, usa el token maestro.

KBC_WORKSPACE_SCHEMA

Esto identifica tu espacio de trabajo en Keboola y se usa para consultas SQL. Sin embargo, esto solo es necesario si estás usando un token de almacenamiento personalizado en lugar del Token Maestro:

Nota: Al crear un espacio de trabajo manualmente, marca la opción Conceder acceso de solo lectura a todos los datos del Proyecto

Nota: KBC_WORKSPACE_SCHEMA se llama Nombre del Dataset en los espacios de trabajo de BigQuery; simplemente haz clic en conectar y copia el Nombre del Dataset

KBC_STORAGE_API_URL (Región de Keboola)

La URL de la API de tu Región de Keboola depende de tu región de despliegue. Puedes determinar tu región mirando la URL en tu navegador cuando hayas iniciado sesión en tu proyecto de Keboola:

RegiónURL de la API
AWS Norteaméricahttps://connection.keboola.com
AWS Europahttps://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 en una rama de desarrollo de Keboola específica, establece el ID de la rama usando el parámetro KBC_BRANCH_ID. El servidor MCP limita su funcionalidad a la rama especificada, asegurando que todos los cambios permanezcan aislados y no impacten la rama de producción.

  • Si no se proporciona, el servidor usa la rama de producción por defecto.
  • Para trabajo de desarrollo, establece KBC_BRANCH_ID al ID numérico de tu rama (ej., 123456). Puedes encontrar el ID de la rama de desarrollo en la URL cuando navegas a la rama de desarrollo en la interfaz de usuario, por ejemplo: https://connection.us-east4.gcp.keboola.com/admin/projects/PROJECT_ID/branch/BRANCH_ID/dashboard.
  • En transportes remotos, puedes sobrescribir por solicitud con la cabecera HTTP X-Branch-Id: <branchId> o KBC_BRANCH_ID: <branchId>.

Instalación

Asegúrate de tener:

  • Python 3.10+ instalado
  • Acceso a un proyecto de Keboola con derechos de administrador
  • Tu cliente MCP preferido (Claude, Cursor, etc.)

Nota: Asegúrate de tener uv instalado. El cliente MCP lo usará para descargar y ejecutar automáticamente el Servidor MCP de 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 más opciones de instalación, consulta la documentación oficial de uv.

Ejecutando el Servidor MCP de Keboola

Hay cuatro formas de usar el Servidor MCP de Keboola, dependiendo de tus necesidades:

Opción A: Modo Integrado (Recomendado)

En este modo, Claude o Cursor inician automáticamente el servidor MCP por ti. No necesitas ejecutar ningún comando en tu terminal.

  1. Configura tu cliente MCP (Claude/Cursor) con los ajustes apropiados
  2. El cliente lanzará automáticamente el servidor MCP cuando sea necesario

Configuración de Claude Desktop

  1. Ve a Claude (esquina superior izquierda de tu pantalla) -> Configuración → Desarrollador → Editar Configuración (si no ves el archivo claude_desktop_config.json, créalo)
  2. Añade la siguiente configuración:
  3. Reinicia Claude Desktop para que los cambios surtan efecto
{
  "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"
      }
    }
  }
}

Ubicaciones del archivo de configuración:

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

Configuración de Cursor

  1. Ve a Configuración → MCP
  2. Haz clic en "+ Añadir nuevo servidor MCP global"
  3. Configura con estos ajustes:
{
  "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: Usa nombres cortos y descriptivos para los servidores MCP. Dado que el nombre completo de la herramienta incluye el nombre del servidor y debe mantenerse por debajo de ~60 caracteres, los nombres más largos pueden ser filtrados en Cursor y no se mostrarán al Agente.

Configuración de Cursor para Windows WSL

Al ejecutar el servidor MCP desde el Subsistema de Windows para Linux con Cursor AI, usa esta configuración:

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

Opción B: Modo de Desarrollo Local

Para desarrolladores que trabajan en el código del servidor MCP en sí:

  1. Clona el repositorio y configura un entorno local
  2. Configura Claude/Cursor para usar tu ruta local de Python:
{
  "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"
      }
    }
  }
}

Opción C: Modo CLI Manual (Solo para pruebas)

Puedes ejecutar el servidor manualmente en una terminal para pruebas o depuración:

# 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 es principalmente para depuración o pruebas. Para uso normal con Claude o Cursor, no necesitas ejecutar manualmente el servidor.

Nota: El servidor usará el transporte HTTP Transmisible y escuchará en localhost:8000 para conexiones entrantes en /mcp. Puedes usar los parámetros --port y --host para hacer que escuche en otro lugar.

Opción 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: El servidor usará el transporte HTTP Transmisible y escuchará en localhost:8000 para conexiones entrantes en /mcp. Puedes cambiar -p para mapear el puerto del contenedor a otro lugar.

¿Necesito iniciar el servidor yo mismo?

Escenario¿Necesitas ejecutarlo manualmente?Usa esta configuración
Usando Claude/CursorNoConfigura MCP en los ajustes de la aplicación
Desarrollando MCP localmenteNo (Claude lo inicia)Apunta la configuración a la ruta de python
Probando CLI manualmenteUsa la terminal para ejecutar
Usando DockerEjecuta el contenedor docker

Usando el Servidor MCP

Una vez que tu cliente MCP (Claude/Cursor) esté configurado y funcionando, puedes empezar a consultar tus datos de Keboola:

Verifica tu configuración

Puedes empezar con una consulta simple para confirmar que todo funciona:

What buckets and tables are in my Keboola project?

Ejemplos de lo que puedes hacer

Exploración de datos:

  • "¿Qué tablas contienen información de clientes?"
  • "Ejecuta una consulta para encontrar los 10 principales clientes por ingresos"

Análisis de datos:

  • "Analiza mis datos de ventas por región para el último trimestre"
  • "Encuentra correlaciones entre la edad del cliente y la frecuencia de compra"

Pipelines de datos:

  • "Crea una transformación SQL que una las tablas de clientes y pedidos"
  • "Inicia el trabajo de extracción de datos para mi componente de Salesforce"

Compatibilidad

Soporte de clientes MCP

Cliente MCPEstado de soporteMétodo de conexión
Claude (Desktop y Web)✅ soportadostdio
Cursor✅ soportadostdio
Windsurf, Zed, Replit✅ Soportadostdio
Codeium, Sourcegraph✅ SoportadoHTTP Transmisible
Clientes MCP personalizados✅ SoportadoHTTP Transmisible o stdio

Herramientas soportadas

Nota: Tus agentes de IA se ajustarán automáticamente a las nuevas herramientas.

Para una lista completa de herramientas disponibles con descripciones detalladas, parámetros y ejemplos de uso, consulta TOOLS.md.

Solución de problemas

Problemas comunes

ProblemaSolución
Errores de autenticaciónVerifica que KBC_STORAGE_TOKEN sea válido
Problemas con el espacio de trabajoConfirma que KBC_WORKSPACE_SCHEMA sea correcto
Tiempo de espera de conexiónVerifica la conectividad de red

Desarrollo

Instalación

Configuración básica:

uv sync --extra dev

Con la configuración básica, puedes usar uv run tox para ejecutar pruebas y verificar el estilo del código.

Configuración recomendada:

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

Con la configuración recomendada, se instalarán paquetes para pruebas y verificación de estilo de código, lo que permite a IDEs como VsCode o Cursor verificar el código o ejecutar pruebas durante el desarrollo.

Pruebas de integración

Para ejecutar pruebas de integración localmente, usa uv run tox -e integtests. NOTA: Necesitarás establecer las siguientes variables de entorno:

  • INTEGTEST_POOL_STORAGE_API_URL
  • INTEGTEST_STORAGE_TOKENS
  • INTEGTEST_STORAGE_TOKEN_STORAGE_BRANCHES

Para obtener estos valores, necesitas proyectos de Keboola dedicados para pruebas de integración. Cada sesión de prueba crea su propio espacio de trabajo de solo lectura, por lo que no es necesario configurar ningún esquema de espacio de trabajo. Consulta integtests/README.md para instrucciones detalladas de configuración y documentación de diseño.

Actualizando uv.lock

Actualiza el archivo uv.lock si has añadido o eliminado dependencias. También considera actualizar el bloqueo con versiones más recientes de dependencias al crear un lanzamiento (uv lock --upgrade).

Actualizando la documentación de herramientas

Cuando realices cambios en las descripciones de cualquier herramienta (docstrings en las funciones de herramienta), debes regenerar el archivo de documentación TOOLS.md para reflejar estos cambios:

uv run python -m src.keboola_mcp_server.generate_tool_docs

Lanzamientos

No hacemos un lanzamiento por cada PR fusionado. El trabajo llega a la rama principal (main) de forma continua, y lanzamos periódicamente una vez que los cambios han sido probados nuevamente juntos — esto evita romper configuraciones que funcionan para los usuarios.

Un lanzamiento se realiza empujando una o dos etiquetas de git:

  • vX.Y.Z — el lanzamiento del servidor MCP (siempre)
  • agent-vX.Y.Z — el lanzamiento del Agente en Plataforma (solo cuando el agente también se lanza)

Cualquiera de las etiquetas activa la CI de release.yml, que construye y publica la imagen Docker. KaiBench se ejecuta solo en etiquetas de producción vX.Y.Z (no en agent-vX.Y.Z, y no en prelanzamientos -dev.). Usa la habilidad release-notes — prepara las notas de lanzamiento y el PR preliminar y guía a través del etiquetado de ambos vX.Y.Z y agent-vX.Y.Z.

Soporte y comentarios

⭐ La forma principal de obtener ayuda, reportar errores o solicitar funcionalidades es abriendo un issue en GitHub. ⭐

El equipo de desarrollo monitorea activamente los issues y responderá lo más rápido posible. Para información general sobre Keboola, por favor usa los recursos a continuación.

Recursos

Conectar