Kestra Python MCP Endpoint

This gateway component facilitates interaction with the Kestra orchestration engine via the MCP protocol. Deployment is often streamlined using containerization.

Docker Deployment Strategy

Running the gateway within a Docker container is recommended to isolate environments and manage dependencies effortlessly.

Kestra AI Agent Integration

Refer to docs/flows/kestra_mcp_docker.yaml for examples concerning Kestra AI Agent usage.

Configuration for Open Source (OSS) Users

Incorporate the subsequent JSON structure into your MCP configuration settings (e.g., within Cursor, Claude, or 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" } } } }

Configuration for Enterprise Edition (EE) Users

{ "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": "", "KESTRA_TENANT_ID": "main", "KESTRA_MCP_LOG_LEVEL": "ERROR" } } } }

Comprehensive Docker Setup

{ "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": "", "KESTRA_TENANT_ID": "main", "KESTRA_USERNAME": "admin", "KESTRA_PASSWORD": "admin", "KESTRA_MCP_DISABLED_TOOLS": "ee", "KESTRA_MCP_LOG_LEVEL": "ERROR" } } } }

Configuration Notes: - Substitute placeholders like <your_kestra_api_token> with active credentials. Note that OSS setups favor KESTRA_USERNAME/KESTRA_PASSWORD over KESTRA_API_TOKEN. - To suppress Enterprise Edition tools when running OSS, specify KESTRA_MCP_DISABLED_TOOLS=ee. - The host.docker.internal DNS resolves to the host machine's network interface, enabling container-to-host communication (e.g., reaching Kestra on port 8080) on standard Docker desktop environments (macOS/Windows). Linux users might require network bridge configuration. - Environment variables are injected into the Docker runtime via the -e arguments.

Tool Manifest

This gateway exposes the following operational tools:

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

Note on EE Tools: The ee toolset is restricted to EE/Cloud subscriptions. OSS users should either omit credentials that grant EE access or explicitly disable these tools via KESTRA_MCP_DISABLED_TOOLS=ee in their configuration.

Optionally, you may maintain an environment file (e.g., .env) to specify tools you wish to exclude globally. For instance, to disable file operations:

dotenv KESTRA_MCP_DISABLED_TOOLS=files

Multiple tool exclusions are comma-separated:

dotenv KESTRA_MCP_DISABLED_TOOLS=ee,kv

Verbosity Control

The logging threshold defaults to ERROR to minimize operational chatter. Adjust verbosity using KESTRA_MCP_LOG_LEVEL:

dotenv

Default: Only critical errors reported

KESTRA_MCP_LOG_LEVEL=ERROR

Include warnings

KESTRA_MCP_LOG_LEVEL=WARNING

Include informational messages

KESTRA_MCP_LOG_LEVEL=INFO

Full diagnostic output

KESTRA_MCP_LOG_LEVEL=DEBUG

When deployed via Docker, this variable must be set within the MCP configuration block:

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

---

Local Development Setup

To facilitate direct modification and debugging, you can execute the server outside of a container. Ensure a Python virtual environment is established first:

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

Establish an environment configuration file (e.g., .env) mirroring the structure of .env_example. Authentication preference is dictated by your Kestra setup: use KESTRA_API_TOKEN for EE/Cloud, or KESTRA_USERNAME/KESTRA_PASSWORD for OSS. Remember to include KESTRA_MCP_DISABLED_TOOLS=ee in the .env file if running OSS and wishing to restrict EE tools.

Following setup, proceed to test the locally hosted endpoint within your preferred AI client (Cursor, Windsurf, VS Code, or Claude Desktop).

---

Client Integration (Cursor, Windsurf, VS Code, or Claude Desktop)

To enable Python MCP interaction with compatible AI environments, first ascertain the path to your uv executable:

bash which uv

Use the returned path in the command section of your configuration. Critically, substitute the placeholder --directory argument with the absolute location of the cloned Kestra MCP Server repository source directory (e.g., /Users/annageller/gh/mcp-server-python/src). Example configuration:

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

This configuration snippet is suitable for direct insertion into Cursor or Claude Developer settings.

VS Code Specific Configuration

Within your project root, create the directory structure .vscode/ and place the configuration within a file named mcp.json. Note that VS Code uses the top-level key servers instead of mcpServers:

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

A dedicated 'Start' button should materialize; activate it to initialize the server.

Subsequently, navigate to the Agent mode within the GitHub Copilot interface to begin tool interaction. An exemplary prompt: "Retrieve all workflows defined in the 'tutorial' tenant space."

Execution will yield the command output directly in the designated output panel.

Frequently Asked Questions

Q: Is continuous manual server operation necessary?

A: Negative. When employing the standard stdio transport mechanism, the AI client (Cursor, Windsurf, VS Code, Claude Desktop) automatically manages the MCP server as a child process. Communication—JSON-RPC messages—is exchanged via standard input (server receives) and standard output (server transmits).

Q: Must the Python virtual environment be manually activated?

A: No, this is circumvented by leveraging uv. Unlike conventional shell activation which modifies environment variables like PATH, uv directly targets the Python interpreter and dependencies housed within the .venv directory. Ensure the environment is provisioned via uv venv and dependencies installed with uv pip install as previously detailed.