Kestra Python MCP Server

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

GitHub
30
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 del Agente IA de Kestra

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.

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 prefieras deshabilitar. Por ejemplo, si deseas deshabilitar las herramientas de Namespace Files, agrega esto a tu archivo .env:

KESTRA_MCP_DISABLED_TOOLS=files

Para deshabilitar varias herramientas, sepáralas con comas:

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

Al usar 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 IDE 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 desarrollador de Claude.

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: "Lista todos los flujos en el namespace tutorial".

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 IDE/chat-interfaces de IA (Cursor, Windsurf, VS Code o Claude Desktop) lanzan el servidor MCP como un subproceso. Este subproceso se comunica con los IDE 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.