🚀 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
安裝了所需的包,如前面部分所述。