mcp -python

The Kestra Python MCP Server is provided as a Docker image for running the Kestra MCP integration inside a container. It exposes a set of MCP tools (such as backfill, execution, files, flow, kv, namespace, replay, restart, resume and the Enterprise Edition tools group ee) that can be invoked by your MCP client. By configuring a single mcpServers entry that points to the Docker image, you enable your MCP-enabled IDEs or platforms (Cursor, Windsurf, VS Code, Claude Desktop, etc.) to manage Kestra flows, namespaces and artifacts via the MCP protocol. You can disable specific tools (for OSS) by setting KESTRA_MCP_DISABLED_TOOLS in your environment, for example to disable the EE tools you would set KESTRA_MCP_DISABLED_TOOLS=ee.

To use the server with your MCP client, paste a configuration block into your MCP settings (Cursor, Claude, VS Code, etc.) that points to the docker-based server. The image runs the Kestra MCP server inside Docker and uses environment variables to configure how it connects to the Kestra API endpoint and authentication. The available tools include: backfill, execution, files, flow, kv, namespace, replay, restart, resume, and the ee tooling group when enabled. When running, the MCP client sends JSON-RPC commands to the server to perform tasks like listing flows, running backfills, executing tasks, and interacting with files and namespaces.

Prerequisites:

• Docker installed and running on your host machine
• Access to the Kestra API if using external hosting

1. Install Docker (if not already installed)

• Windows/MM: download Docker Desktop from https://www.docker.com/products/docker-desktop
• macOS: install via Docker Desktop or Homebrew
• Linux: install docker and docker-compose via your distro's package manager

2. Prepare MCP configuration

• Create or edit your MCP client configuration to include the kestra server entry. For example, in your MCP settings paste:

{
  "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"
      }
    }
  }
}

3. Start the server via your MCP client or by applying the config in your MCP tool

• The docker command will pull and run the image, exposing the Kestra MCP server inside the container.

4. Verify connectivity

• Ensure the host can reach the Kestra API at the configured KEESTRA_BASE_URL (default http://host.docker.internal:8080/api/v1).
• In your MCP client, test a simple command like listing namespaces or flows to validate that the MCP server communicates with Kestra.

Notes and tips:

• If you are on Linux and host.docker.internal is not available, consider using the host network mode or the container's bridge networking with the appropriate host IP.
• To disable Enterprise Edition tools, set KESTRA_MCP_DISABLED_TOOLS=ee in your environment or in the JSON config under env.
• The MCP_LOG_LEVEL can be set to DEBUG, INFO, WARNING, or ERROR to control verbosity; default shown is ERROR to minimize noise.
• You can reuse the same mcpServers entry across multiple MCP clients; the server image will run as a container responding to JSON-RPC commands from the MCP protocol.
• For OSS installations, you may provide KESTRA_USERNAME and KESTRA_PASSWORD for basic auth; EE/Cloud installations can use KESTRA_API_TOKEN instead.