How to add Kestra Python MCP Server to Windsurf

Control Kestra workflow orchestration — manage flows, executions, files, KV and more from your AI client. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 27★ · stdio · apikey

Windsurf config for Kestra Python MCP Server

{
  "mcpServers": {
    "kestra-python-mcp-server": {
      "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"
      }
    }
  }
}

Requires Docker to be installed and running.

Setup steps

1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
2Paste the Kestra Python MCP Server config below.
3Fill in placeholder secrets, then save.
4Click Refresh in the MCP panel.
5Kestra Python MCP Server's tools become available to Cascade.

Before you start

Docker installed (the server runs as a Docker container)
A running Kestra instance reachable via its REST API (KESTRA_BASE_URL, e.g. http://host.docker.internal:8080/api/v1)
Credentials: a Kestra API token (KESTRA_API_TOKEN) for EE/Cloud, or KESTRA_USERNAME / KESTRA_PASSWORD for OSS
An MCP-compatible client (Claude Desktop, Cursor, Windsurf, or VS Code)

What Kestra Python MCP Server can do in Windsurf

backfill

Run backfills to execute a flow for past scheduled intervals.

ee

Enterprise Edition tools, available only in EE/Cloud editions; can be disabled for OSS via KESTRA_MCP_DISABLED_TOOLS=ee.

execution

Trigger, inspect and manage flow executions.

files

Work with Kestra namespace files.

flow

List, view and manage Kestra flows.

kv

Read and write entries in the Kestra KV (key-value) store.

logs

Retrieve execution and task logs.

namespace

Manage Kestra namespaces.

Security

Authenticates to your Kestra instance with a Kestra API token (KESTRA_API_TOKEN) for EE/Cloud, or basic auth (KESTRA_USERNAME / KESTRA_PASSWORD) for OSS. Store these credentials securely and avoid committing them. The server has broad control over your orchestration platform (executions, files, KV store), so scope its access appropriately. OSS users should set KESTRA_MCP_DISABLED_TOOLS=ee to disable Enterprise Edition tools.

Kestra Python MCP Server + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Kestra Python MCP Server config there under the "mcpServers" key and restart the client.

Is Kestra Python MCP Server safe to use with Windsurf?

Do I have to manually start the server as an always-on process?

No. With the stdio transport, AI clients (Cursor, Windsurf, VS Code, Claude Desktop) launch the MCP server as a subprocess and communicate via JSON-RPC over stdin/stdout.

How do I authenticate against an OSS Kestra instance?

Use basic authentication by setting KESTRA_USERNAME and KESTRA_PASSWORD instead of KESTRA_API_TOKEN. EE/Cloud installations use the KESTRA_API_TOKEN.

How do I disable Enterprise Edition tools on an OSS install?

Set KESTRA_MCP_DISABLED_TOOLS=ee. You can disable multiple tool groups by separating them with commas (e.g. KESTRA_MCP_DISABLED_TOOLS=files).

View repo Full Kestra Python MCP Server page