How to add Kestra Python MCP Server to Claude Desktop

Control Kestra workflow orchestration — manage flows, executions, files, KV and more from your AI client. Paste the config into ~/Library/Application Support/Claude/claude_desktop_config.json and restart Claude Desktop.

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

Claude Desktop 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 Claude Desktop → Settings → Developer → Edit Config (this opens ~/Library/Application Support/Claude/claude_desktop_config.json).
2Paste the Kestra Python MCP Server config below under the top-level "mcpServers" key.
3Fill in any placeholder secrets (API keys, paths) in the snippet.
4Save the file, then fully quit and reopen Claude Desktop.
5Open a chat and confirm Kestra Python MCP Server's tools appear under the 🔌 tools menu.

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 Claude Desktop

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 + Claude Desktop FAQ

Where is the Claude Desktop config file?

Claude Desktop reads MCP servers from ~/Library/Application Support/Claude/claude_desktop_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 Claude Desktop?

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