Kestra Python MCP Server

Uma implementação em Python de um servidor Model Context Protocol para interagir com o Kestra.

GitHub
33
Experimente este MCPPatrocinado

Documentação

Kestra Python MCP Server

Você pode executar o MCP Server em um contêiner Docker. Isso é útil se você quiser evitar o gerenciamento de ambientes Python ou dependências na sua máquina local.

Usando o Kestra AI Agent

Consulte kestra_mcp_docker.

Configuração mínima para usuários OSS

Cole a seguinte configuração nas suas configurações de MCP (por exemplo, Cursor, Claude ou 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"
      }
    }
  }
}

Configuração mínima para usuários 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"
      }
    }
  }
}

Configuração detalhada 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:

  • Substitua <your_kestra_api_token>, <your_google_api_key> e <your_helicone_api_key> pelas suas credenciais reais.
  • Para instalações OSS, você pode usar KESTRA_USERNAME e KESTRA_PASSWORD em vez de KESTRA_API_TOKEN.
  • Para desabilitar as ferramentas da Enterprise Edition no OSS, defina KESTRA_MCP_DISABLED_TOOLS=ee.
  • O hostname host.docker.internal permite que o contêiner Docker acesse serviços em execução na sua máquina host (como o servidor de API do Kestra na porta 8080). Isso funciona no macOS e no Windows. No Linux, você pode precisar usar o modo de rede do host ou configurar uma bridge personalizada.
  • Os flags -e passam variáveis de ambiente da sua configuração MCP para o contêiner Docker.

Suporte de versões do Kestra

Tanto o Kestra 1.x quanto o Kestra 2.x são suportados pela mesma imagem, e nada precisa ser configurado para nenhum deles.

Vários endpoints foram alterados no Kestra 2.0. As ações de execução foram movidas para /actions/, os parâmetros de busca por endpoint foram substituídos pelo modelo unificado filters[field][OPERATION], a criação de backfill foi movida para /triggers/backfill/create e a listagem de KV foi movida para GET /kv. Um parâmetro de consulta 1.x enviado a um servidor 2.x é ignorado em vez de rejeitado, então uma solicitação pode parecer bem-sucedida enquanto os resultados retornam sem filtro.

A versão do servidor é lida uma vez de GET /api/v1/configs na primeira chamada de ferramenta e cada solicitação é então construída para essa versão principal. Quando esse endpoint está inacessível, por exemplo, atrás de um proxy que não o encaminha, a versão principal pode ser definida explicitamente:

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

Duas diferenças entre as versões principais permanecem visíveis na saída da ferramenta:

  • Dashboards - a partir do 2.0, os dashboards só podem ser criados via API na Enterprise Edition, então generate_dashboard com auto_create retorna o YAML gerado junto com um aviso no OSS 2.x.
  • Movimentações de arquivos de namespace - no Kestra 2.x, um arquivo gravado em um caminho que foi movido anteriormente é armazenado sob um nome versionado, e uma movimentação posterior desse caminho falha com erro 500. O erro é relatado com a sugestão de excluir e reenviar em vez disso.

Ferramentas disponíveis

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

Nota: O grupo de ferramentas ee contém funcionalidades específicas da Enterprise Edition e está disponível apenas nas edições EE/Cloud. Para usuários OSS, você pode desabilitar as ferramentas EE adicionando KESTRA_MCP_DISABLED_TOOLS=ee ao seu arquivo .env.

Opcionalmente, você pode incluir KESTRA_MCP_DISABLED_TOOLS no seu arquivo .env listando as ferramentas que você prefere desabilitar. Por exemplo, se você quiser desabilitar as ferramentas de Namespace Files, adicione isso ao seu arquivo .env:

KESTRA_MCP_DISABLED_TOOLS=files

Para desabilitar várias ferramentas, separe-as com vírgula:

KESTRA_MCP_DISABLED_TOOLS=ee

Configuração de logging

Por padrão, o servidor MCP registra apenas mensagens de nível ERROR para minimizar o ruído. Você pode controlar o nível de logging usando a variável de ambiente 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

Ao usar Docker, adicione a variável de ambiente à sua configuração 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"
      }
    }
  }
}

Desenvolvimento local

Para executar o MCP Server para Kestra localmente (por exemplo, se você quiser estendê-lo com novas ferramentas), certifique-se de criar um ambiente virtual primeiro:

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

Crie um arquivo .env no diretório raiz do projeto semelhante ao arquivo .env_example. Para instalações OSS, você pode usar autenticação básica com KESTRA_USERNAME e KESTRA_PASSWORD. Para instalações EE/Cloud, use KESTRA_API_TOKEN. Para desabilitar as ferramentas da Enterprise Edition no OSS, adicione KESTRA_MCP_DISABLED_TOOLS=ee ao seu arquivo .env.

Em seguida, siga as instruções abaixo explicando como testar seu servidor local no Cursor, Windsurf, VS Code ou Claude Desktop.

Uso no Cursor, Windsurf, VS Code ou Claude Desktop

Para usar o Python MCP Server com Claude ou IDEs modernas, primeiro verifique qual é o caminho para o uv na sua máquina:

which uv

Copie o caminho retornado por which uv e cole-o na seção command. Em seguida, substitua o --directory pelo caminho onde você clonou o repositório do Kestra MCP Server. Por exemplo:

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

Você pode colar isso nas configurações de MCP do Cursor ou nas configurações do Claude Developer.

Configuração no VS Code

No diretório do seu projeto no VS Code, adicione uma pasta .vscode e, dentro dessa pasta, crie um arquivo chamado mcp.json. Cole sua configuração MCP nesse arquivo (observe que no VS Code, a chave é servers em vez de mcpServers):

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

Um pequeno botão Start deve aparecer; clique nele para iniciar o servidor.

img.png

Se você agora navegar até a aba GitHub Copilot e mudar para o modo Agente, poderá interagir diretamente com as ferramentas do Kestra MCP Server. Por exemplo, tente digitar o prompt: "List all flows in the tutorial namespace".

img_1.png

Se você clicar em continuar, verá o resultado do comando na janela de saída.

img_2.png

FAQ

Pergunta: Preciso iniciar o servidor manualmente como um processo sempre ativo?

Não, você não precisa executar o servidor manualmente, pois ao usar o transporte stdio, os IDEs/interfaces de chat de IA (Cursor, Windsurf, VS Code ou Claude Desktop) iniciam o servidor MCP como um subprocesso. Esse subprocesso se comunica com os IDEs de IA via mensagens JSON-RPC pelos fluxos de entrada e saída padrão. O servidor recebe mensagens pelo stdin e envia respostas pelo stdout.

Pergunta: Preciso ativar manualmente o ambiente virtual para o MCP Server?

Não, porque usamos uv. Diferentemente dos gerenciadores de pacotes Python tradicionais, onde a ativação do ambiente virtual modifica variáveis de shell como PATH, uv usa diretamente o interpretador Python e os pacotes do diretório .venv sem exigir que variáveis de ambiente sejam definidas primeiro. Apenas certifique-se de ter criado um ambiente virtual uv com uv venv e instalado os pacotes necessários com uv pip install conforme descrito na seção anterior.