Keboola

Servidor MCP de Keboola

Conecta tus agentes de IA, clientes MCP (Cursor, Claude, Windsurf, VS Code ...) y otros asistentes de IA con Keboola. Expón datos, transformaciones, consultas SQL y activadores de trabajos, sin necesidad de código de integración. Proporciona a los agentes los datos adecuados cuando y donde los necesiten.

Descripción general

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

• Inicio rápido
• Configuración local

Funciones

Con AI Agent y MCP Server, puedes:

• Almacenamiento: Consultar tablas directamente y administrar las descripciones de tablas o buckets
• Componentes: Crear, enumerar e inspeccionar extractores, escritores, aplicaciones de datos y configuraciones de transformaciones
• SQL: Crear transformaciones SQL usando lenguaje natural
• Trabajos: Ejecutar componentes y transformaciones, y obtener detalles de ejecución de trabajos
• Flujos: Crear y administrar canalizaciones de flujos de trabajo mediante Conditional Flows y Orchestrator Flows.
• Aplicaciones de datos: Crear, implementar y administrar aplicaciones de datos de Keboola que muestran tus consultas sobre los datos del almacenamiento: aplicaciones python-js en un repositorio administrado por Keboola o en un repositorio de GitHub del cliente (clonado mediante la conexión de GitHub de la organización, sin credenciales almacenadas), y aplicaciones Streamlit.
• Metadatos: Buscar, leer y actualizar la documentación del proyecto y los metadatos de los objetos usando lenguaje natural
• Ramas de desarrollo: Trabajar de forma segura en ramas de desarrollo fuera de producción, donde todas las operaciones se limitan a la rama seleccionada.

---

🚀 Inicio rápido: Remote MCP Server (la forma más sencilla)

La forma más sencilla de usar Keboola MCP Server es mediante nuestro Remote MCP Server. Esta solución alojada elimina la necesidad de configuración, ajustes o instalación locales.

¿Qué es Remote MCP Server?

Nuestro servidor remoto está alojado en cada stack multiinquilino de Keboola y admite autenticación OAuth. Puedes conectarte desde cualquier asistente de IA compatible con conexiones remotas Streamable HTTP y autenticación OAuth.

Cómo conectarse

1. Obtén la URL de tu servidor remoto: Ve a la configuración de tu proyecto de Keboola → pestaña MCP Server
2. Copia la URL del servidor: Tendrá un aspecto similar a 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 inicies sesión con tu cuenta de Keboola. Después, se elige en la conversación en qué proyecto(s) trabajar (por ejemplo, «enumera mis proyectos de Keboola» / «usa el proyecto X»).

Clientes compatibles

• Cursor: Usa el botón «Install In Cursor» en la configuración de MCP Server de tu proyecto o haz clic en este botón
• Claude Desktop: Añade la integración desde Settings → Integrations
• Claude Code: Instálalo con claude mcp add --transport http keboola <URL> (consulta los detalles más abajo)
• Windsurf: Configúralo con la URL del servidor remoto
• Make: Configúralo con la URL del servidor remoto
• Otros clientes MCP: Configúralos 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 desde el terminal. Puedes instalar la integración de Keboola MCP Server con un comando sencillo.

Instalación:

Ejecuta el siguiente comando en el terminal y sustituye <YOUR_REGION> por tu región de Keboola:

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

Comandos específicos de cada región:

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

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

Autenticación:

La primera vez que uses Keboola MCP Server en Claude Code, se abrirá una ventana del navegador que te pedirá:

1. Iniciar sesión con tu cuenta de Keboola
2. Autorizar la conexión

Después de autenticarte, podrás usar las herramientas de Keboola directamente desde Claude Code. La selección del proyecto se realiza después, en la conversación: solo tienes que preguntarle a Claude qué proyecto(s) de Keboola usar.

Para obtener instrucciones detalladas de configuración y URL específicas de cada 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 MCP Servers alojados de forma remota respetan el parámetro KBC_BRANCH_ID y limitan todas las operaciones a la rama especificada. Puedes encontrar el ID de la rama de desarrollo en la URL al abrirla 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 mediante el encabezado X-Branch-Id: <branchId>; de lo contrario, MCP Server usa la rama de producción de forma predeterminada. El cliente de IA o el entorno que gestiona la conexión con el servidor debe encargarse de esto.

Autorización de herramientas y control de acceso

Al usar transportes basados en HTTP (Streamable HTTP), puedes controlar qué herramientas están disponibles para los clientes mediante encabezados HTTP. Esto resulta útil para restringir las capacidades de los agentes de IA o aplicar políticas de cumplimiento.

Encabezados de autorización

Encabezado	Descripción	Ejemplo
X-Allowed-Tools	Lista de herramientas permitidas, separadas por comas	get_configs,get_buckets,query_data
X-Disallowed-Tools	Lista de herramientas que se deben excluir, separadas por comas	create_config,run_job
X-Read-Only-Mode	Restringir el acceso únicamente a herramientas de solo lectura	true, 1 o yes

Comportamiento de los filtros

Los filtros se aplican en este orden: permitidas → intersección con solo lectura → exclusión de las no permitidas. Los encabezados vacíos no imponen restricciones.

Herramientas de solo lectura

Las herramientas de solo lectura son las anotadas con readOnlyHint=True. Estas herramientas solo recuperan información y no realizan cambios en tu proyecto de Keboola. Para consultar la lista actual de herramientas de solo lectura, consulta el archivo TOOLS.md, que es una instantánea generada automáticamente del conjunto real de herramientas.

Ejemplo: acceso de solo lectura

X-Read-Only-Mode: true

Carga diferida de herramientas

Encabezado	Descripción	Ejemplo
X-Deferred-Tools	Lista de herramientas que se deben enumerar con _meta["anthropic/alwaysLoad"] = false	run_sync_action,get_flow_schema

Los clientes Claude Code / Claude Agent SDK que registran el servidor con alwaysLoad: true mantienen estas herramientas diferidas y disponibles mediante la búsqueda de herramientas, en lugar de cargar sus definiciones de antemano. El encabezado solo cambia los metadatos de tools/list; no oculta ni autoriza herramientas. Un encabezado vacío o nombres de herramientas desconocidos no producen cambios.

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

Seguridad a nivel de fila y de columna

Las políticas a nivel de fila y de columna son objetos de Keboola Metastore (rls-policy, cls-policy), creados con kbagent rls / kbagent cls. Este servidor no las lee ni las aplica. En un proyecto que tenga la función row-level-security, crea su espacio de trabajo (la configuración mcp-workspace-<hex> del componente keboola.mcp-server-tool) con el tipo de inicio de sesión de Connection governed. Un espacio de trabajo gobernado no tiene credenciales: solo Query Service puede leerlo, y Query Service filtra cada resultado de query_data según las políticas del proyecto. Este servidor no reescribe nada ni ofrece una alternativa: lo que Query Service rechaza, query_data lo devuelve como error.

• Qué lo activa. Este servidor solo comprueba la función del proyecto; Connection no necesita ninguna función ni rol para crear un espacio de trabajo gobernado (Snowflake o BigQuery, sin clave pública). Connection del stack debe aceptar el tipo de inicio de sesión governed para el backend del proyecto: si no lo acepta, rechaza la creación y, a continuación, fallan todas las herramientas que necesitan el espacio de trabajo (no hay alternativa que use un espacio de trabajo normal). Un espacio de trabajo MCP normal más antiguo no se elimina: se omite en cuanto se activa la función. Con la función activada, solo se acepta un pin workspace_schema o X-Workspace-Id para un espacio de trabajo gobernado (uno normal permitiría eludir las políticas), por lo que se rechaza un pin al espacio de trabajo antiguo o al espacio de trabajo normal propio de una aplicación de datos; elimina el antiguo.
• Denegación predeterminada. Query Service rechaza una tabla de un espacio de trabajo gobernado a la que no se aplique ningún rls-policy (una regla "*" abre una tabla a todos los lectores identificados); un cls-policy por sí solo no concede filas. Se ejecuta una instrucción que no lee ninguna tabla (SELECT 1). El rechazo llega al agente como Row-level security does not allow this query.
• Quién es el lector. Query Service identifica al lector mediante el token propio del administrador del proyecto: el token programático que reenvía este servidor (kbc_at_ / kbc_pat_, incluido el PAT secundario de un ámbito de varios proyectos, enviado con X-KBC-ProjectId) o el token maestro de Storage propio del administrador. Cualquier otro token (una integración, una aplicación de datos, Kai) no identifica a ningún usuario final, carece de identidad verificada y no puede leer nada de una tabla gobernada. Las reglas de grupo nunca coinciden (la identidad no incluye grupos).
• Vinculaciones. Sin una vinculación, un espacio de trabajo recibe todas las políticas del proyecto, y este servidor nunca crea una. Para asignar a un espacio de trabajo solo algunas políticas, vincúlalas a su KID: KID:<stack id>:project-<project id>:workspace-<workspace id> (un espacio de trabajo de la rama predeterminada; un espacio de trabajo de una rama también tiene branch-<branch id> antes de project). El ID del stack es el que tiene configurado Query Service (QUERY_RLS_STACK_ID, por ejemplo, dev-keboola-aws-eu-west-1), el ID del espacio de trabajo aparece en la salida de get_project_info, y kbagent rls bind --project P --workspace-id WS --rls-policy ID --stack-id S crea la vinculación. Una vinculación solo restringe las políticas, se aplica a la siguiente consulta y no se transfiere a otra sesión de espacio de trabajo: una sesión de rama o un espacio de trabajo que se vuelve a crear tiene un KID nuevo y vuelve a empezar con todas las políticas.
• Límites. El ID del espacio de trabajo del servidor también es el que recibe una aplicación de datos como WORKSPACE_ID cuando no se le aprovisiona un espacio de trabajo independiente; la aplicación consulta con su propio token, carece de identidad verificada y no puede leer nada de las tablas gobernadas.
• Metadatos. Las herramientas de metadatos solo muestran lo que Query Service permite leer al usuario. get_tables y search (que en ese caso no usa la búsqueda global, ya que sus recuentos incluyen las tablas ocultas) omiten las tablas que el usuario no puede leer, y get_tables indica que no se encontró una tabla solicitada por ID; una tabla con una política de columnas solo muestra las columnas permitidas por la política (también en su clave principal y en lo que coincide con search). Una tabla legible se muestra sin el número de filas ni su tamaño, ya que esos valores cuentan las filas ocultas por una política de filas. get_buckets sigue enumerando todos los buckets, pero sin el número de tablas ni el tamaño, que cuentan las tablas ocultas. Esto requiere el endpoint de Query Service POST /api/v1/branches/{branch}/workspaces/{workspace}/rls/scope y falla de forma segura: cuando Query Service no puede determinarlo, una herramienta de un proyecto gobernado devuelve un error con un mensaje breve y sin tablas. Los proyectos sin esta función no se ven afectados ni realizan llamadas adicionales.

---

Configuración local de MCP Server (modo personalizado o de desarrollo)

Ejecuta MCP Server en tu propio equipo para tener control total y facilitar el desarrollo. Elige esta opción si quieres personalizar herramientas, depurar localmente o iterar rápidamente. Instalarás el servidor, te autenticarás (un inicio de sesión único en el navegador, sin tener que pegar ningún token) y lo iniciarás. Este enfoque ofrece la máxima flexibilidad (herramientas personalizadas, registros locales e iteración sin conexión), pero requiere configuración manual y tendrás que gestionar las actualizaciones y los secretos por tu cuenta. El servidor admite varias opciones de transporte, que se pueden seleccionar proporcionando el argumento --transport <transport> al iniciar el servidor:

• stdio - Valor predeterminado cuando no se especifica --transport. Entrada/salida estándar, normalmente se usa para implementaciones locales con un solo cliente.
• streamable-http - Ejecuta el servidor de forma remota a través de HTTP con un canal de transmisión bidireccional, lo que permite que el cliente y el servidor intercambien mensajes continuamente. Conéctate mediante /mcp (por ejemplo, http://localhost:8000/mcp).
• http-compat - Alias de streamable-http, que se mantiene por compatibilidad con versiones anteriores.

Para trabajar con tu proyecto de Keboola, el servidor necesita dos cosas: tu región de Keboola (KBC_STORAGE_API_URL) y un método para autenticarse. La opción recomendada es iniciar sesión una vez en el navegador: nunca tendrás que crear, copiar ni pegar un token. Opcionalmente, configura KBC_BRANCH_ID para trabajar en una rama de desarrollo.

Algunas variables no se obtienen de los encabezados de la solicitud:

• KBC_STORAGE_API_URL: un servidor iniciado con su propia URL de Storage API (el parámetro --api-url o la variable de entorno KBC_STORAGE_API_URL) solo sirve a esa pila de Keboola. Se ignora un encabezado X-Storage-Api-Url que solicite otro host (se registra una advertencia); el servidor conserva su propia URL para la solicitud. Inicia el servidor sin una URL de Storage API propia si quieres que cada solicitud elija su pila.
• KBC_KUBERNETES_TOKEN_PATH (solo servidores implementados; consulta docs/kubernetes-sa-auth.md): se lee únicamente del entorno, nunca de un encabezado.
• KBC_WORKSPACE_ID / KBC_WORKSPACE_SCHEMA: funciona igual que la URL de Storage API anterior: un servidor iniciado con su propia asignación de espacio de trabajo (mediante cualquiera de las dos variables o --workspace-id) conserva esa asignación para todas las solicitudes; se ignora un encabezado X-Workspace-Id o X-Workspace-Schema que solicite otro espacio de trabajo (se registra una advertencia). Un servidor sin asignación propia (el caso compartido multiusuario) sigue tomando la asignación de la solicitud, en cada solicitud, como se describe a continuación.

Iniciar sesión

Inicia sesión una vez con el navegador; el servidor guarda la sesión y la renueva automáticamente, así que no hay tokens que gestionar:

uvx keboola_mcp_server login --api-url https://connection.YOUR_REGION.keboola.com

Esto abre el navegador para iniciar sesión en Keboola y luego guarda la sesión para toda la pila en ~/.keboola/mcp/credentials.json (solo tú puedes leerla; hay una entrada por pila). Después, inicia el servidor con solo KBC_STORAGE_API_URL configurado; no se necesita ningún token. Los proyectos en los que trabajar se eligen más adelante, durante la conversación (get_accessible_projects / set_project_scope), no durante el inicio de sesión.

Comando	Qué hace
login --api-url <url>	Inicia sesión en una pila
login --force	Vuelve a iniciar sesión / cambia de cuenta
login --show-token	Imprime el token de sesión actual (depuración)
logout [--api-url <url>] [--all]	Elimina la sesión guardada de una pila (o de todas las pilas)

Cuando inicias el servidor mediante stdio en un terminal interactivo sin una sesión guardada, este inicia automáticamente el proceso de inicio de sesión en el navegador la primera vez. Los clientes MCP (Claude, Cursor, …) ejecutan el servidor en segundo plano, donde no se puede abrir un navegador, así que ejecuta login tú mismo una vez antes.

Iniciar sin una cuenta de Keboola

También puedes iniciar el servidor con solo KBC_STORAGE_API_URL y sin credenciales. Se inicia en modo de arranque: las herramientas que necesitan acceso a Keboola explican cómo obtener credenciales, y una herramienta funciona sin ellas: create_project. Esta crea un proyecto de Keboola, inicia la sesión en él y devuelve una URL de confirmación. Al abrir esa URL en un navegador e iniciar sesión, el proyecto pasa a ser tuyo de forma permanente; hasta entonces es temporal y Keboola puede recuperarlo. Una vez que lo confirmes, se revoca la sesión creada por la herramienta y continúas con tu propio login.

Esto requiere una pila con el aprovisionamiento de agentes habilitado; en otros casos, la herramienta indica que no está disponible.

También es posible hacer lo mismo sin ejecutar un servidor, en un servidor MCP alojado de forma remota cuyo operador lo haya habilitado (KBC_ALLOW_ANONYMOUS_PROVISIONING): esa implementación también ofrece https://mcp.<stack>/mcp-anonymous, que no requiere credenciales. Dirige tu cliente allí sin autenticación, llama a create_project y sigue trabajando en el proyecto creado por esa llamada: el servidor guarda las credenciales por ti y la herramienta devuelve un scope_token opaco que debes volver a enviar en llamadas posteriores. Tiene una URL independiente porque el endpoint normal /mcp debe seguir rechazando las solicitudes no autenticadas: ese rechazo es lo que indica a los clientes MCP que deben iniciar el inicio de sesión OAuth. Una vez que reclames el proyecto, cambia a /mcp e inicia sesión con la cuenta que ahora es su propietaria.

Autenticarse sin un navegador

Para contenedores o CI donde no sea posible iniciar sesión en un navegador, proporciona directamente un token de acceso o token de acceso personal de Keboola: configura KBC_STORAGE_TOKEN (variable de entorno) o envía el encabezado X-StorageAPI-Token, junto con KBC_PROJECT_ID (o el encabezado X-KBC-ProjectId) para seleccionar el proyecto. En los transportes HTTP, se pueden proporcionar por solicitud como encabezados, de modo que cada solicitud incluya sus propias credenciales.

KBC_WORKSPACE_ID

Fija las consultas a un espacio de trabajo específico ya existente mediante su ID, en lugar de usar la búsqueda basada en esquemas descrita anteriormente. Tiene prioridad sobre KBC_WORKSPACE_SCHEMA cuando ambos están configurados. Esta es la opción que proporciona un llamador de Data App / kai-agent mediante el encabezado X-Workspace-Id, para que Kai integrado en esa aplicación consulte únicamente a través de su propio espacio de trabajo.

Se configura mediante la variable de entorno KBC_WORKSPACE_ID, la opción de CLI --workspace-id o, por solicitud en implementaciones multiusuario, el encabezado X-Workspace-Id.

KBC_STORAGE_API_URL (región de Keboola)

La URL de la API de tu región de Keboola depende de la región de implementación. Puedes determinar tu región consultando la URL del navegador cuando hayas iniciado sesión en tu proyecto de Keboola:

Región	URL de la 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 trabajar en una rama de desarrollo de Keboola específica, configura el ID de la rama mediante el parámetro KBC_BRANCH_ID. El servidor MCP limita su funcionalidad a la rama especificada, lo que garantiza que todos los cambios permanezcan aislados y no afecten a la rama de producción.

• Si no se proporciona, el servidor usa la rama de producción de forma predeterminada.
• Para trabajar en desarrollo, configura KBC_BRANCH_ID con el ID numérico de tu rama (por ejemplo, 123456). Puedes encontrar el ID de la rama de desarrollo en la URL al navegar a esa rama 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 anularlo por solicitud con el encabezado HTTP X-Branch-Id: <branchId> o KBC_BRANCH_ID: <branchId>.

Instalación

Asegúrate de tener:

• Python 3.11+ 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 Keboola MCP Server. Instalación de 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 ver más opciones de instalación, consulta la documentación oficial de uv.

Ejecutar Keboola MCP Server

Hay cuatro formas de usar Keboola MCP Server, según tus necesidades:

Opción A: Modo integrado (recomendado)

En este modo, Claude o Cursor inicia automáticamente el servidor MCP por ti.

1. Inicia sesión una vez en un terminal para guardar una sesión (el cliente ejecuta el servidor en segundo plano, donde no se puede abrir un navegador):

   uvx keboola_mcp_server login --api-url https://connection.YOUR_REGION.keboola.com
   

2. Configura tu cliente MCP (Claude/Cursor) con los ajustes siguientes; solo se necesita KBC_STORAGE_API_URL.
3. El cliente iniciará automáticamente el servidor MCP cuando sea necesario.

Configuración de Claude Desktop

1. Ve a Claude (esquina superior izquierda de la pantalla) -> Settings → Developer → Edit Config (si no ves 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_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 Settings → MCP
2. Haz clic en «+ Add new global MCP Server»
3. Configúralo 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_BRANCH_ID": "your_branch_id_optional"
      }
    }
  }
}

Nota: Usa nombres cortos y descriptivos para los servidores MCP. Como el nombre completo de la herramienta incluye el nombre del servidor y debe tener menos de ~60 caracteres, los nombres más largos pueden quedar filtrados en Cursor y no aparecerán para el agente.

Configuración de Cursor para Windows WSL

Al ejecutar el servidor MCP desde Windows Subsystem for 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_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 directamente en el código del servidor MCP:

1. Clona el repositorio y configura un entorno local
2. Configura Claude/Cursor para que use 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_BRANCH_ID": "your_branch_id_optional"
      }
    }
  }
}

Opción C: Modo CLI manual (solo para pruebas)

Puedes ejecutar el servidor manualmente en un terminal para hacer pruebas o depurar:

# Sign in once (stores a session under ~/.keboola/mcp), then start the server.
export KBC_STORAGE_API_URL=https://connection.YOUR_REGION.keboola.com
uvx keboola_mcp_server login --api-url "$KBC_STORAGE_API_URL"

uvx keboola_mcp_server --transport streamable-http

Nota: Este modo se usa principalmente para depuración o pruebas. Para el uso normal con Claude o Cursor, no es necesario ejecutar el servidor manualmente.

Nota: El servidor usará el transporte Streamable HTTP y escuchará en localhost:8000 las conexiones entrantes en /mcp. Puedes usar los parámetros --port y --host para que escuche en otra dirección.

Opción D: Usar Docker

Un contenedor no puede abrir un navegador, así que autentícate con un token (consulta Autenticarse sin un navegador): configura KBC_STORAGE_TOKEN con un token de acceso o de acceso personal de Keboola y KBC_PROJECT_ID con el proyecto de destino. (En HTTP, puedes pasar en su lugar los encabezados X-StorageAPI-Token / X-KBC-ProjectId en cada solicitud y omitir estas variables).

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_TOKEN" \
  -e KBC_PROJECT_ID="YOUR_PROJECT_ID" \
  -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 Streamable HTTP y escuchará en localhost:8000 las conexiones entrantes en /mcp. Puedes cambiar -p para asignar el puerto del contenedor a otro puerto.

¿Tengo que iniciar el servidor yo mismo?

Escenario	¿Hay que ejecutarlo manualmente?	Usa esta configuración
Usar Claude/Cursor	No	Configura MCP en los ajustes de la aplicación
Desarrollar MCP localmente	No (Claude lo inicia)	Indica la ruta de Python en la configuración
Probar la CLI manualmente	Sí	Ejecútalo desde el terminal
Usar Docker	Sí	Ejecuta el contenedor de Docker

Usar MCP Server

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

Verificar la configuración

Puedes empezar con una consulta sencilla 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 clientes principales por ingresos»

Análisis de datos:

• «Analiza mis datos de ventas por región del último trimestre»
• «Encuentra correlaciones entre la edad de los clientes 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

Compatibilidad con clientes MCP

Cliente MCP	Estado de compatibilidad	Método de conexión
Claude (Desktop y Web)	✅ compatible	stdio
Cursor	✅ compatible	stdio
Windsurf, Zed, Replit	✅ Compatible	stdio
Codeium, Sourcegraph	✅ Compatible	Streamable HTTP
Clientes MCP personalizados	✅ Compatible	Streamable HTTP o stdio

Herramientas compatibles

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

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

Solución de problemas

Problemas comunes

Problema	Solución
Errores de autenticación	Vuelve a ejecutar keboola_mcp_server login (o, si te autenticas con un token, verifica el token y KBC_PROJECT_ID)
Tiempo de espera de conexión	Comprueba 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 comprobar 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 realizar pruebas y comprobar el estilo del código, lo que permite que los IDE, como VsCode o Cursor, comprueben el código o ejecuten pruebas durante el desarrollo.

Pruebas de integración

Para ejecutar pruebas de integración localmente, usa uv run tox -e integtests. NOTA: Tendrás que configurar 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 específicos para las 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 obtener instrucciones detalladas de configuración y documentación de diseño.

Actualización de uv.lock

Actualiza el archivo uv.lock si has añadido o eliminado dependencias. Considera también actualizar el archivo de bloqueo con versiones más recientes de las dependencias al crear una versión (uv lock --upgrade).

Actualización de la documentación de las herramientas

Cuando realices cambios en las descripciones de las herramientas (docstrings en las funciones de las herramientas), debes volver a generar el archivo de documentación TOOLS.md para reflejar esos cambios:

uv run python -m src.keboola_mcp_server.generate_tool_docs

Publicación de versiones

No publicamos una versión por cada PR fusionada. Los cambios se incorporan continuamente a la rama principal (main) y publicamos versiones periódicamente, una vez que se han vuelto a probar en conjunto; así evitamos interrumpir las configuraciones que funcionan para los usuarios.

Una versión se publica enviando una o dos etiquetas de git:

• vX.Y.Z — la versión del servidor MCP (siempre)
• agent-vX.Y.Z — la versión de In Platform Agent (solo cuando también se publica el agente)

Cualquiera de las dos etiquetas activa release.yml CI, que compila y publica la imagen de Docker. KaiBench solo se ejecuta con etiquetas de producción vX.Y.Z (no con agent-vX.Y.Z ni con versiones preliminares -dev.). Usa la habilidad release-notes: prepara las notas de la versión y un PR preliminar, y te guía para etiquetar tanto vX.Y.Z como agent-vX.Y.Z.

Soporte y comentarios

⭐ La forma principal de obtener ayuda, informar de errores o solicitar funciones es abrir una incidencia en GitHub. ⭐

El equipo de desarrollo supervisa activamente las incidencias y responderá lo antes posible. Para obtener información general sobre Keboola, consulta los recursos siguientes.

Recursos

• Documentación para usuarios
• Documentación para desarrolladores
• Plataforma Keboola
• Seguimiento de incidencias ← Método de contacto principal para MCP Server

Conecta

• LinkedIn
• Twitter
• Registro de cambios