Only show ERROR messages (default)

1## Kestra Python MCP Server
2 
3You can run the MCP Server in a Docker container. This is useful if you want to avoid managing Python environments or dependencies on your local machine.
4 
5### Using Kestra AI Agent
6 
7See [kestra_mcp_docker](docs/flows/kestra_mcp_docker.yaml).
8 
9### Minimal configuration for OSS users
10 
11Paste the following configuration into your MCP settings (e.g., Cursor, Claude, or VS Code):
12 
13```json
14{
15  "mcpServers": {
16    "kestra": {
17      "command": "docker",
18      "args": [
19        "run",
20        "-i",
21        "--rm",
22        "--pull",
23        "always",
24        "-e",
25        "KESTRA_BASE_URL",
26        "-e",
27        "KESTRA_TENANT_ID",
28        "-e",
29        "KESTRA_MCP_DISABLED_TOOLS",
30        "-e",
31        "KESTRA_MCP_LOG_LEVEL",
32        "-e",
33        "KESTRA_USERNAME",
34        "-e",
35        "KESTRA_PASSWORD",
36        "ghcr.io/kestra-io/mcp-server-python:latest"
37      ],
38      "env": {
39        "KESTRA_BASE_URL": "http://host.docker.internal:8080/api/v1",
40        "KESTRA_TENANT_ID": "main",
41        "KESTRA_MCP_DISABLED_TOOLS": "ee",
42        "KESTRA_MCP_LOG_LEVEL": "ERROR",
43        "KESTRA_USERNAME": "admin@kestra.io",
44        "KESTRA_PASSWORD": "your_password"
45      }
46    }
47  }
48}
49```
50 
51### Minimal configuration for EE users
52 
53```json
54{
55  "mcpServers": {
56    "kestra": {
57      "command": "docker",
58      "args": [
59        "run",
60        "-i",
61        "--rm",
62        "--pull",
63        "always",
64        "-e", "KESTRA_BASE_URL",
65        "-e", "KESTRA_API_TOKEN",
66        "-e", "KESTRA_TENANT_ID",
67        "-e", "KESTRA_MCP_LOG_LEVEL",
68        "ghcr.io/kestra-io/mcp-server-python:latest"
69      ],
70      "env": {
71        "KESTRA_BASE_URL": "http://host.docker.internal:8080/api/v1",
72        "KESTRA_API_TOKEN": "<your_kestra_api_token>",
73        "KESTRA_TENANT_ID": "main",
74        "KESTRA_MCP_LOG_LEVEL": "ERROR"
75      }
76    }
77  }
78}
79```
80 
81### Detailed Configuration using Docker
82 
83```json
84{
85  "mcpServers": {
86    "kestra": {
87      "command": "docker",
88      "args": [
89        "run",
90        "-i",
91        "--rm",
92        "--pull",
93        "always",
94        "-e", "KESTRA_BASE_URL",
95        "-e", "KESTRA_API_TOKEN",
96        "-e", "KESTRA_TENANT_ID",
97        "-e", "KESTRA_USERNAME",
98        "-e", "KESTRA_PASSWORD",
99        "-e", "KESTRA_MCP_DISABLED_TOOLS",
100        "-e", "KESTRA_MCP_LOG_LEVEL",
101        "ghcr.io/kestra-io/mcp-server-python:latest"
102      ],
103      "env": {
104        "KESTRA_BASE_URL": "http://host.docker.internal:8080/api/v1",
105        "KESTRA_API_TOKEN": "<your_kestra_api_token>",
106        "KESTRA_TENANT_ID": "main",
107        "KESTRA_USERNAME": "admin",
108        "KESTRA_PASSWORD": "admin",
109        "KESTRA_MCP_DISABLED_TOOLS": "ee",
110        "KESTRA_MCP_LOG_LEVEL": "ERROR"
111      }
112    }
113  }
114}
115```
116 
117**Notes:**
118- Replace `<your_kestra_api_token>`, `<your_google_api_key>`, and `<your_helicone_api_key>` with your actual credentials.
119- For OSS installations, you can use `KESTRA_USERNAME` and `KESTRA_PASSWORD` instead of `KESTRA_API_TOKEN`.
120- To disable Enterprise Edition tools in OSS, set `KESTRA_MCP_DISABLED_TOOLS=ee`.
121- The `host.docker.internal` hostname allows the Docker container to access services running on your host machine (such as the Kestra API server on port 8080). This works on macOS and Windows. On Linux, you may need to use the host network mode or set up a custom bridge.
122- The `-e` flags pass environment variables from your MCP configuration into the Docker container. 
123 
124---
125 
126### Available Tools
127 
128- 🔄 backfill
129- ⚙️ ee (Enterprise Edition tools)
130- ▶️ execution
131- 📁 files
132- 🔀 flow
133- 🗝️ kv
134- 🌐 namespace
135- 🔁 replay
136- ♻️ restart
137- ⏸️ resume
138 
139**Note:** The `ee` tool group contains Enterprise Edition specific functionality and is only available in EE/Cloud editions. For OSS users, you can disable EE tools by adding `KESTRA_MCP_DISABLED_TOOLS=ee` to your `.env` file.
140 
141Optionally, you can include `KESTRA_MCP_DISABLED_TOOLS` in your `.env` file listing the tools that you prefer to disable. For example, if you want to disable Namespace Files tools, add this to your `.env` file:
142 
143```dotenv
144KESTRA_MCP_DISABLED_TOOLS=files
145```
146 
147To disable multiple tools, separate them with comma:
148 
149```dotenv
150KESTRA_MCP_DISABLED_TOOLS=ee
151```
152 
153### Logging Configuration
154 
155By default, the MCP server only logs ERROR level messages to minimize noise. You can control the logging level using the `KESTRA_MCP_LOG_LEVEL` environment variable:
156 
157```dotenv
158# Only show ERROR messages (default)
159KESTRA_MCP_LOG_LEVEL=ERROR
160 
161# Show WARNING and ERROR messages
162KESTRA_MCP_LOG_LEVEL=WARNING
163 
164# Show INFO, WARNING, and ERROR messages
165KESTRA_MCP_LOG_LEVEL=INFO
166 
167# Show all messages including DEBUG
168KESTRA_MCP_LOG_LEVEL=DEBUG
169```
170 
171When using Docker, add the environment variable to your MCP configuration:
172 
173```json
174{
175  "mcpServers": {
176    "kestra": {
177      "command": "docker",
178      "args": [
179        "run",
180        "-i",
181        "--rm",
182        "--pull",
183        "always",
184        "-e", "KESTRA_BASE_URL",
185        "-e", "KESTRA_MCP_LOG_LEVEL",
186        "ghcr.io/kestra-io/mcp-server-python:latest"
187      ],
188      "env": {
189        "KESTRA_BASE_URL": "http://host.docker.internal:8080/api/v1",
190        "KESTRA_MCP_LOG_LEVEL": "ERROR"
191      }
192    }
193  }
194}
195```
196 
197---
198 
199### Local development
200 
201To run the MCP Server for Kestra locally (e.g. if you want to extend it with new tools), make sure to create a virtual environment first:
202 
203```bash
204uv venv --python 3.13
205uv pip install -r requirements.txt
206```
207 
208Create an `.env` file in the root directory of the project similar to the [.env_example](.env_example) file. For OSS installations, you can use basic authentication with `KESTRA_USERNAME` and `KESTRA_PASSWORD`. For EE/Cloud installations, use `KESTRA_API_TOKEN`. To disable Enterprise Edition tools in OSS, add `KESTRA_MCP_DISABLED_TOOLS=ee` to your `.env` file.
209 
210Then, follow the instructions below explaining how to test your local server in Cursor, Windsurf, VS Code or Claude Desktop.
211 
212---
213 
214### Usage in Cursor, Windsurf, VS Code or Claude Desktop
215 
216To use the Python MCP Server with Claude or modern IDEs, first check what is the path to uv on your machine:
217 
218```bash
219which uv
220```
221 
222Copy the path returned by `which uv` and paste it into the `command` section.
223Then, replace the `--directory` by the path where you cloned the Kestra MCP Server repository. For example:
224 
225```json
226{
227  "mcpServers": {
228    "kestra": {
229      "command": "/Users/annageller/.local/bin/uv",
230      "args": [
231        "--directory",
232        "/Users/annageller/gh/mcp-server-python/src",
233        "run",
234        "server.py"
235      ]
236    }
237  }
238}
239```
240 
241You can paste that in the Cursor MCP settings or Claud Developer settings.
242 
243### VS Code setup
244 
245In your VS Code project directory, add a folder `.vscode` and within that folder, create a file called `mcp.json`. Paste your MCP configuration into that file (note that in VS Code, the key is `servers` instead of `mcpServers`):
246 
247```json
248{
249  "servers": {
250    "kestra": {
251      "command": "/Users/annageller/.local/bin/uv",
252      "args": [
253        "--directory",
254        "/Users/annageller/gh/mcp-server-python/src",
255        "run",
256        "server.py"
257      ]
258    }
259  }
260}
261```
262 
263A small `Start` button should show up, click on it to start the server.
264 
265![img.png](docs/images/vscode1.png)
266 
267If you now navigate to the GitHub Copilot tab and switch to the Agent mode, you will be able to directly interact with the Kestra MCP Server tools. For example, try typing the prompt: "List all flows in the tutorial namespace".
268 
269![img_1.png](docs/images/vscode2.png)
270 
271If you click on continue, you will see the result of the command in the output window.
272 
273![img_2.png](docs/images/vscode3.png)
274 
275### FAQ
276 
277**Question: Do I have to manually start the server as an always-on process?**
278 
279No, you don't have to run the server manually, as when using the `stdio` transport, the AI IDEs/chat-interfaces (Cursor, Windsurf, VS Code or Claude Desktop) launch the MCP server as a subprocess. This subprocess communicates with AI IDEs via JSON-RPC messages over standard input and output streams. The server receives messages through stdin and sends responses through stdout.
280 
281**Question: Do I have to manually activate the virtual environment for the MCP Server?**
282 
283No, because we use `uv`. Unlike traditional Python package managers, where virtual environment activation modifies shell variables like `PATH`, `uv` directly uses the Python interpreter and packages from the `.venv` directory without requiring environment variables to be set first. Just make sure you have created a uv virtual environment with `uv venv` and installed the required packages with `uv pip install` as described in the previous section.
284 
285