mcp-server-python - Kestra Python MCP Server支持多环境运行，集成流程管理等工具功能的Beta版服务器

探索

MCP Server Python

Kestra Python MCP Server是一个Beta版的工具服务器，用于与Kestra工作流平台交互，支持通过Docker容器或本地开发环境运行，提供多种工具功能如流程管理、执行控制等。

开发者工具云平台 #工作流工具 #Python服务 #Docker部署 .Python

评分 : 2分

下载量 : 6.5K

更新时间 : 2025-07-24

打开站点

什么是 Kestra Python MCP Server?

Kestra Python MCP Server 是一个用于与 Kestra 平台交互的工具服务器，允许用户通过命令行或 IDE（如 VS Code、Cursor）调用 Kestra 的功能，例如管理流程、执行任务、查看日志等。

如何使用 Kestra Python MCP Server?

Kestra Python MCP Server 可以通过 Docker 容器运行，也可以在本地开发环境中启动。用户可以通过配置文件设置环境变量，并在 IDE 中集成该服务器以直接与 Kestra 交互。

适用场景

适用于需要与 Kestra 流程平台进行交互的开发者，包括流程管理、任务执行、日志查看、依赖分析等场景。

主要功能

流程管理

可以创建、更新、删除、执行和查看流程。

任务执行

支持执行特定任务，并提供执行状态和日志信息。

依赖分析

能够展示流程之间的依赖关系，帮助理解整个工作流结构。

日志查看

提供对流程和任务执行日志的访问和查看功能。

多平台支持

支持在 VS Code、Cursor、Claude 等多种开发环境中集成使用。

优势

简化了与 Kestra 平台的交互方式

支持多种开发环境，便于集成

提供了丰富的命令和功能，满足日常开发需求

局限性

目前处于 Beta 阶段，可能存在不稳定性

部分高级功能仅在企业版中可用

需要一定的配置和环境设置

如何使用

安装依赖

确保已安装 uv 和 Python 3.13，然后创建虚拟环境并安装依赖。

配置环境变量

根据使用的 Kestra 版本（OSS 或 EE），设置相应的环境变量。

运行 MCP Server

使用 uv 运行 server.py 文件来启动 MCP 服务器。

在 IDE 中集成

在 VS Code、Cursor 等 IDE 中配置 MCP 服务器路径和参数，即可开始使用。

使用案例

列出流程依赖关系

用户想要了解某个命名空间下的流程依赖结构，以便优化工作流设计。

重新执行失败任务

用户发现某个任务执行失败，希望重新运行该任务。

查看流程日志

用户需要查看某次流程执行的日志，以便排查问题。

常见问题

是否需要手动启动 MCP 服务器？

MCP 服务器是否支持企业版功能？

如何解决 Docker 容器无法连接到 Kestra API 的问题？

MCP 服务器的性能如何？

安装

复制以下命令到你的Client进行配置

{
  "mcpServers": {
    "kestra": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--pull",
        "always",
        "-e", "KESTRA_BASE_URL",
        "-e", "KESTRA_TENANT_ID",
        "-e", "KESTRA_MCP_DISABLED_TOOLS",
        "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"
      }
    }
  }
}

{
  "mcpServers": {
    "kestra": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--pull",
        "always",
        "-e",
        "KESTRA_MCP_DISABLED_TOOLS",
        "-e",
        "KESTRA_BASE_URL",
        "-e",
        "KESTRA_TENANT_ID",
        "-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_USERNAME": "admin@kestra.io",
        "KESTRA_PASSWORD": "your_password"
      }
    }
  }
}

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

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

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

注意：您的密钥属于敏感信息，请勿与任何人分享。

🚀 Kestra Python MCP Server

Kestra Python MCP Server 是一个用于 Kestra 的工具，可在 Docker 容器中运行，为用户提供便捷的任务处理和管理功能。它支持不同版本的 Kestra，包括开源版（OSS）和企业版（EE），并提供了丰富的工具集，方便用户进行任务回填、执行、文件管理等操作。

🚀 快速开始

你可以在 Docker 容器中运行 MCP 服务器。如果你想避免在本地机器上管理 Python 环境或依赖项，这将非常有用。

📦 安装指南

OSS 用户的最小配置

将以下配置粘贴到你的 MCP 设置中（例如 Cursor、Claude 或 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",
        "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"
      }
    }
  }
}

如果你启用了基本身份验证，请使用：

{
  "mcpServers": {
    "kestra": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--pull",
        "always",
        "-e",
        "KESTRA_MCP_DISABLED_TOOLS",
        "-e",
        "KESTRA_BASE_URL",
        "-e",
        "KESTRA_TENANT_ID",
        "-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_USERNAME": "admin@kestra.io",
        "KESTRA_PASSWORD": "your_password"
      }
    }
  }
}

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_DISABLED_TOOLS",
        "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"
      }
    }
  }
}

使用 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",
        "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"
      }
    }
  }
}

⚠️ 重要提示

请将 <your_kestra_api_token>、<your_google_api_key> 和 <your_helicone_api_key> 替换为你实际的凭证。

对于 OSS 安装，你可以使用 KESTRA_USERNAME 和 KESTRA_PASSWORD 代替 KESTRA_API_TOKEN。

要在 OSS 中禁用企业版工具，请设置 KESTRA_MCP_DISABLED_TOOLS=ee。

host.docker.internal 主机名允许 Docker 容器访问运行在你主机上的服务（例如端口 8080 上的 Kestra API 服务器）。这在 macOS 和 Windows 上有效。在 Linux 上，你可能需要使用主机网络模式或设置自定义桥接。

-e 标志将 MCP 配置中的环境变量传递到 Docker 容器中。

✨ 主要特性

可用工具

🔄 backfill：回填任务
⚙️ ee（企业版工具）
▶️ execution：执行任务
📁 files：文件管理
🔀 flow：流程管理
🗝️ kv：键值存储
🌐 namespace：命名空间管理
🔁 replay：重放任务
♻️ restart：重启任务
⏸️ resume：恢复任务

⚠️ 重要提示

ee 工具组包含企业版特定功能，仅在 EE/Cloud 版本中可用。对于 OSS 用户，你可以通过在 .env 文件中添加 KESTRA_MCP_DISABLED_TOOLS=ee 来禁用 EE 工具。

你可以选择在 .env 文件中包含 KESTRA_MCP_DISABLED_TOOLS，列出你想要禁用的工具。例如，如果你想禁用命名空间文件工具，请在 .env 文件中添加：

KESTRA_MCP_DISABLED_TOOLS=files

要禁用多个工具，请用逗号分隔：

KESTRA_MCP_DISABLED_TOOLS=ee

💻 使用示例

本地开发

要在本地运行 Kestra 的 MCP 服务器（例如，如果你想使用新工具扩展它），请确保首先创建一个虚拟环境：

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

在项目的根目录下创建一个 .env 文件，类似于 .env_example 文件。对于 OSS 安装，你可以使用 KESTRA_USERNAME 和 KESTRA_PASSWORD 进行基本身份验证。对于 EE/Cloud 安装，请使用 KESTRA_API_TOKEN。要在 OSS 中禁用企业版工具，请在 .env 文件中添加 KESTRA_MCP_DISABLED_TOOLS=ee。

在 Cursor、Windsurf、VS Code 或 Claude Desktop 中使用

要在 Claude 或现代 IDE 中使用 Python MCP 服务器，首先检查你机器上 uv 的路径：

which uv

复制 which uv 返回的路径，并将其粘贴到 command 部分。然后，将 --directory 替换为你克隆 Kestra MCP 服务器存储库的路径。例如：

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

你可以将其粘贴到 Cursor MCP 设置或 Claud 开发者设置中。

VS Code 设置

在你的 VS Code 项目目录中，添加一个 .vscode 文件夹，并在该文件夹中创建一个名为 mcp.json 的文件。将你的 MCP 配置粘贴到该文件中（注意，在 VS Code 中，键是 servers 而不是 mcpServers）：

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

会出现一个小的 Start 按钮，点击它启动服务器。如果你现在导航到 GitHub Copilot 选项卡并切换到代理模式，你将能够直接与 Kestra MCP 服务器工具进行交互。例如，尝试输入提示：“列出教程命名空间中的所有流程”。如果你点击继续，你将在输出窗口中看到命令的结果。

使用 Kestra MCP 服务器与 Google Agent SDK (ADK)

要启动 Agent Development UI，请运行以下命令：

source .venv/bin/activate  
cd agents/
adk web

然后，从代理下拉列表中选择 google-mcp-client 并开始发送提示以与 Kestra MCP 服务器进行交互。

建议启用 “Token Streaming” 切换开关，以便在生成响应时进行流式传输。

如需更多信息，请查看官方 adk-python 存储库。对于 Java 开发者，有一个等效的 adk-java。

使用 Kestra MCP 服务器与 OpenAI Agent SDK

假设在 company 命名空间中有以下 Kestra 流程：你可以从项目根目录运行以下命令，将所有这些依赖项可视化为 ASCII 图：

uv run agents/openai-mcp-client/agent.py -p 'List dependencies for the namespace company'

你应该会看到类似的输出：

Here's the dependency graph for the namespace `company`:

flow1 ────▶ flow2
            flow2 ────▶ flow3b
                        flow3b ────▶ flow4
                                     flow4 ────▶ flow5
                                                 flow5 ────▶ flow6
                                                             flow6
            flow2 ────▶ flow3c
                        flow3c ────▶ flow4
                        flow3c ====▶ flow3
                                     flow3
            flow2 ────▶ flow3a
                        flow3a ────▶ flow4
goodbye
hello
scheduled_flow

**Legend:**
- `────▶` FLOW_TRIGGER  (基于流程触发的依赖)
- `====▶` FLOW_TASK     (基于子流程任务的依赖)

没有箭头列出的流程在此命名空间中没有依赖项。

📚 详细文档

常见问题解答

问题：我是否需要手动将服务器作为始终运行的进程启动？ 不需要，当使用 stdio 传输时，AI IDE/聊天界面（Cursor、Windsurf、VS Code 或 Claude Desktop）会将 MCP 服务器作为子进程启动。这个子进程通过标准输入和输出流上的 JSON-RPC 消息与 AI IDE 进行通信。服务器通过 stdin 接收消息并通过 stdout 发送响应。

问题：我是否需要手动激活 MCP 服务器的虚拟环境？ 不需要，因为我们使用 uv。与传统的 Python 包管理器不同，传统的虚拟环境激活会修改 PATH 等 shell 变量，而 uv 直接使用 .venv 目录中的 Python 解释器和包，无需先设置环境变量。只需确保你已经使用 uv venv 创建了 uv 虚拟环境，并使用 uv pip install 安装了所需的包，如前面部分所述。