shield_lock
金大哥
← 返回 MCP 目录
public公开dns本地运行

mcp-server-python

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

article

README

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

使用 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 流程： img.png 你可以从项目根目录运行以下命令，将所有这些依赖项可视化为 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 安装了所需的包，如前面部分所述。

help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端