Kestra Python MCP Server

Una implementación en Python de un servidor del Protocolo de Contexto de Modelo para interactuar con Kestra.

GitHub
33
Prueba este MCPPatrocinado

Documentación

Kestra Python MCP Server

Puedes ejecutar el MCP Server en un contenedor Docker. Esto es útil si deseas evitar gestionar entornos Python o dependencias en tu máquina local.

Uso con Kestra AI Agent

Consulta kestra_mcp_docker.

Configuración mínima para usuarios OSS

Pega la siguiente configuración en tu configuración de MCP (por ejemplo, Cursor, Claude o VS Code):

{
  "mcpServers": {
    "kestra": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--pull",
        "always",
        "-e",
        "KESTRA_BASE_URL",
        "-e",
        "KESTRA_TENANT_ID",
        "-e",
        "KESTRA_MCP_DISABLED_TOOLS",
        "-e",
        "KESTRA_MCP_LOG_LEVEL",
        "-e",
        "KESTRA_USERNAME",
        "-e",
        "KESTRA_PASSWORD",
        "ghcr.io/kestra-io/mcp-server-python:latest"
      ],
      "env": {
        "KESTRA_BASE_URL": "http://host.docker.internal:8080/api/v1",
        "KESTRA_TENANT_ID": "main",
        "KESTRA_MCP_DISABLED_TOOLS": "ee",
        "KESTRA_MCP_LOG_LEVEL": "ERROR",
        "KESTRA_USERNAME": "admin@kestra.io",
        "KESTRA_PASSWORD": "your_password"
      }
    }
  }
}

Configuración mínima para usuarios EE

{
  "mcpServers": {
    "kestra": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--pull",
        "always",
        "-e", "KESTRA_BASE_URL",
        "-e", "KESTRA_API_TOKEN",
        "-e", "KESTRA_TENANT_ID",
        "-e", "KESTRA_MCP_LOG_LEVEL",
        "ghcr.io/kestra-io/mcp-server-python:latest"
      ],
      "env": {
        "KESTRA_BASE_URL": "http://host.docker.internal:8080/api/v1",
        "KESTRA_API_TOKEN": "<your_kestra_api_token>",
        "KESTRA_TENANT_ID": "main",
        "KESTRA_MCP_LOG_LEVEL": "ERROR"
      }
    }
  }
}

Configuración detallada usando Docker

{
  "mcpServers": {
    "kestra": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--pull",
        "always",
        "-e", "KESTRA_BASE_URL",
        "-e", "KESTRA_API_TOKEN",
        "-e", "KESTRA_TENANT_ID",
        "-e", "KESTRA_USERNAME",
        "-e", "KESTRA_PASSWORD",
        "-e", "KESTRA_MCP_DISABLED_TOOLS",
        "-e", "KESTRA_MCP_LOG_LEVEL",
        "ghcr.io/kestra-io/mcp-server-python:latest"
      ],
      "env": {
        "KESTRA_BASE_URL": "http://host.docker.internal:8080/api/v1",
        "KESTRA_API_TOKEN": "<your_kestra_api_token>",
        "KESTRA_TENANT_ID": "main",
        "KESTRA_USERNAME": "admin",
        "KESTRA_PASSWORD": "admin",
        "KESTRA_MCP_DISABLED_TOOLS": "ee",
        "KESTRA_MCP_LOG_LEVEL": "ERROR"
      }
    }
  }
}

Notas:

  • Reemplaza <your_kestra_api_token>, <your_google_api_key> y <your_helicone_api_key> con tus credenciales reales.
  • Para instalaciones OSS, puedes usar KESTRA_USERNAME y KESTRA_PASSWORD en lugar de KESTRA_API_TOKEN.
  • Para deshabilitar las herramientas de Enterprise Edition en OSS, establece KESTRA_MCP_DISABLED_TOOLS=ee.
  • El nombre de host host.docker.internal permite que el contenedor Docker acceda a servicios que se ejecutan en tu máquina host (como el servidor API de Kestra en el puerto 8080). Esto funciona en macOS y Windows. En Linux, es posible que necesites usar el modo de red del host o configurar un puente personalizado.
  • Los indicadores -e pasan variables de entorno desde tu configuración de MCP al contenedor Docker.

Soporte de versiones de Kestra

Tanto Kestra 1.x como Kestra 2.x son compatibles con la misma imagen, y no es necesario configurar nada para ninguna de las dos.

Varios endpoints cambiaron en Kestra 2.0. Las acciones de ejecución se movieron bajo /actions/, los parámetros de búsqueda por endpoint fueron reemplazados por el modelo unificado filters[field][OPERATION], la creación de backfill se movió a /triggers/backfill/create y el listado de KV se movió a GET /kv. Un parámetro de consulta 1.x enviado a un servidor 2.x se ignora en lugar de rechazarse, por lo que una solicitud puede parecer exitosa mientras los resultados llegan sin filtrar.

La versión del servidor se lee una vez desde GET /api/v1/configs en la primera llamada a una herramienta y cada solicitud se construye para esa versión principal. Cuando ese endpoint es inalcanzable, por ejemplo detrás de un proxy que no lo reenvía, la versión principal se puede establecer explícitamente:

# 1, 2, or a full version such as 1.3.3 or 2.0.1
KESTRA_API_VERSION=2

Dos diferencias entre las versiones principales permanecen visibles en la salida de las herramientas:

  • Dashboards: desde 2.0 en adelante, los dashboards solo se pueden crear a través de la API en Enterprise Edition, por lo que generate_dashboard con auto_create devuelve el YAML generado junto con una advertencia en OSS 2.x.
  • Movimientos de archivos de namespace: en Kestra 2.x, un archivo escrito en una ruta que previamente se movió se almacena bajo un nombre versionado, y un movimiento posterior de esa ruta falla con un error 500. El error se informa con la sugerencia de eliminar y volver a subir en su lugar.

Herramientas disponibles

  • 🔄 backfill
  • ⚙️ ee (herramientas de Enterprise Edition)
  • ▶️ execution
  • 📁 files
  • 🔀 flow
  • 🗝️ kv
  • 📋 logs
  • 🌐 namespace
  • 🔁 replay
  • ♻️ restart
  • ⏸️ resume

Nota: El grupo de herramientas ee contiene funcionalidad específica de Enterprise Edition y solo está disponible en las ediciones EE/Cloud. Para usuarios OSS, puedes deshabilitar las herramientas EE agregando KESTRA_MCP_DISABLED_TOOLS=ee a tu archivo .env.

Opcionalmente, puedes incluir KESTRA_MCP_DISABLED_TOOLS en tu archivo .env enumerando las herramientas que prefieres deshabilitar. Por ejemplo, si deseas deshabilitar las herramientas de Namespace Files, agrega esto a tu archivo .env:

KESTRA_MCP_DISABLED_TOOLS=files

Para deshabilitar múltiples herramientas, sepáralas con coma:

KESTRA_MCP_DISABLED_TOOLS=ee

Configuración de registro

Por defecto, el servidor MCP solo registra mensajes de nivel ERROR para minimizar el ruido. Puedes controlar el nivel de registro usando la variable de entorno KESTRA_MCP_LOG_LEVEL:

# Only show ERROR messages (default)
KESTRA_MCP_LOG_LEVEL=ERROR

# Show WARNING and ERROR messages
KESTRA_MCP_LOG_LEVEL=WARNING

# Show INFO, WARNING, and ERROR messages
KESTRA_MCP_LOG_LEVEL=INFO

# Show all messages including DEBUG
KESTRA_MCP_LOG_LEVEL=DEBUG

Cuando uses Docker, agrega la variable de entorno a tu configuración de MCP:

{
  "mcpServers": {
    "kestra": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--pull",
        "always",
        "-e", "KESTRA_BASE_URL",
        "-e", "KESTRA_MCP_LOG_LEVEL",
        "ghcr.io/kestra-io/mcp-server-python:latest"
      ],
      "env": {
        "KESTRA_BASE_URL": "http://host.docker.internal:8080/api/v1",
        "KESTRA_MCP_LOG_LEVEL": "ERROR"
      }
    }
  }
}

Desarrollo local

Para ejecutar el MCP Server para Kestra localmente (por ejemplo, si deseas extenderlo con nuevas herramientas), asegúrate de crear primero un entorno virtual:

uv venv --python 3.13
uv pip install -r requirements.txt

Crea un archivo .env en el directorio raíz del proyecto similar al archivo .env_example. Para instalaciones OSS, puedes usar autenticación básica con KESTRA_USERNAME y KESTRA_PASSWORD. Para instalaciones EE/Cloud, usa KESTRA_API_TOKEN. Para deshabilitar las herramientas de Enterprise Edition en OSS, agrega KESTRA_MCP_DISABLED_TOOLS=ee a tu archivo .env.

Luego, sigue las instrucciones a continuación que explican cómo probar tu servidor local en Cursor, Windsurf, VS Code o Claude Desktop.

Uso en Cursor, Windsurf, VS Code o Claude Desktop

Para usar el Python MCP Server con Claude o IDEs modernos, primero verifica cuál es la ruta a uv en tu máquina:

which uv

Copia la ruta devuelta por which uv y pégala en la sección command. Luego, reemplaza --directory por la ruta donde clonaste el repositorio de Kestra MCP Server. Por ejemplo:

{
  "mcpServers": {
    "kestra": {
      "command": "/Users/annageller/.local/bin/uv",
      "args": [
        "--directory",
        "/Users/annageller/gh/mcp-server-python/src",
        "run",
        "server.py"
      ]
    }
  }
}

Puedes pegar eso en la configuración de MCP de Cursor o en la configuración de Claude Developer.

Configuración en VS Code

En el directorio de tu proyecto de VS Code, agrega una carpeta .vscode y dentro de esa carpeta, crea un archivo llamado mcp.json. Pega tu configuración de MCP en ese archivo (ten en cuenta que en VS Code, la clave es servers en lugar de mcpServers):

{
  "servers": {
    "kestra": {
      "command": "/Users/annageller/.local/bin/uv",
      "args": [
        "--directory",
        "/Users/annageller/gh/mcp-server-python/src",
        "run",
        "server.py"
      ]
    }
  }
}

Debería aparecer un pequeño botón Start, haz clic en él para iniciar el servidor.

img.png

Si ahora navegas a la pestaña de GitHub Copilot y cambias al modo Agente, podrás interactuar directamente con las herramientas del Kestra MCP Server. Por ejemplo, intenta escribir el prompt: "List all flows in the tutorial namespace".

img_1.png

Si haces clic en continuar, verás el resultado del comando en la ventana de salida.

img_2.png

Preguntas frecuentes

Pregunta: ¿Tengo que iniciar manualmente el servidor como un proceso siempre activo?

No, no tienes que ejecutar el servidor manualmente, ya que al usar el transporte stdio, los IDEs de IA/interfaces de chat (Cursor, Windsurf, VS Code o Claude Desktop) lanzan el servidor MCP como un subproceso. Este subproceso se comunica con los IDEs de IA mediante mensajes JSON-RPC a través de los flujos estándar de entrada y salida. El servidor recibe mensajes a través de stdin y envía respuestas a través de stdout.

Pregunta: ¿Tengo que activar manualmente el entorno virtual para el MCP Server?

No, porque usamos uv. A diferencia de los gestores de paquetes Python tradicionales, donde la activación del entorno virtual modifica variables de shell como PATH, uv usa directamente el intérprete de Python y los paquetes del directorio .venv sin requerir que las variables de entorno se establezcan primero. Solo asegúrate de haber creado un entorno virtual uv con uv venv e instalado los paquetes requeridos con uv pip install como se describió en la sección anterior.