qkrun-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@qkrun-mcp run the test task in myapp and stream its output"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
qkrun-mcp
Standalone MCP stdio server for qkrun tasks. It exposes list_tasks and
run_task, with live stdout/stderr notifications, using the official
MCP Python SDK.
The SDK owns framing, initialization, transport, protocol validation, and error
responses. Tool arguments are validated with jsonschema; this project does
not implement the MCP protocol.
Local setup
Requires Python 3.12+ and uv. This project is currently local-only and not yet published. The qkrun runtime is installed from PyPI.
cd ~/projects/qkrun-mcp
uv sync --dev
uv run qkrun-mcp --help
uv run qkrun-mcp --project myapp:/absolute/path/to/myapp/_qkBuilt wheels declare the portable qkrun>=2.1,<3 dependency and never embed
local source paths.
Related MCP server: Codex Control Plane MCP
Client migration
qkrun 2.1 removes its bundled MCP server. Point your client's stdio command at
the standalone qkrun-mcp executable instead:
{
"mcpServers": {
"qkrun": {
"command": "/absolute/path/to/qkrun-mcp/.venv/bin/qkrun-mcp",
"args": ["--project", "myapp:/absolute/path/to/myapp/_qk"]
}
}
}On Windows the executable is .venv/Scripts/qkrun-mcp.exe.
Replace python -m qkrun.mcp with qkrun-mcp or
python -m qkrun_mcp.server using the new environment's Python.
--version now reports the standalone server version, not the runner version.
Server diagnostic logging goes to stderr by default (or --log-file), never
the MCP stdio output.
Tool names, parameters, text JSON results, structured results, stdout/stderr
streaming, stdin, timeouts, project aliases/paths, TOML/JSON config precedence,
and CWD-based discovery are preserved. list_tasks returns a JSON array
(structured content wraps it as {"result": [...]}); run_task returns
{"exit_code": 0, "stdout": "...", "stderr": "..."}. Tool errors are surfaced
as SDK tool errors, and invalid arguments are rejected by jsonschema validation
before execution.
See usage and tool reference for the complete configuration/API.
SDK 2.3 supports both legacy initialization and modern 2026-07-28 connections.
MCP logging is deprecated by SEP-2577, but retained here to preserve streamed
stdout/stderr; the SDK emits MCPDeprecationWarning on these supported paths.
On modern connections clients must opt into logging per request; the SDK's
Client(..., logging_callback=..., log_level="info") handles that opt-in.
Transport and logging negotiation remain SDK-managed.
qkrun integration boundary
The server owns its CLI parser and standard-library logging configuration.
It reuses qkrun._launcher.Launcher for project discovery and executable
resolution rather than duplicating qkrun's launcher logic. This is an internal
qkrun API. Discovery searches ancestors for
_qk/ or _qk.py; executable precedence is _qk virtual environments,
project-root virtual environments, then QK_EXECUTABLE.
For standalone _qk.py modules, the server creates a temporary package wrapper
so qkrun can cache task metadata; the wrapper is removed when the server exits.
The boundary for task execution/metadata is the CLI: prefer each project's
local qk, invoke qk :list --json for metadata, and fall back to
sys.executable -m qkrun in the project root. Subprocesses set
QK_LAUNCHER_RUNNING=true to prevent launcher recursion. Explicit module paths
are normalized to absolute paths before changing the subprocess directory.
The installed runner must support :list --json (qkrun 2.1+).
Tasks execute arbitrary project code: only register projects you trust.
Dependency choice
The user approved replacing FastMCP with the official SDK before dependency changes. Counts below include the named root package, its extras and transitive runtime dependencies, exclude development packages, and include conditional packages across platforms. Counts are not vulnerability findings.
Resolution | Packages |
Original qkrun checked-in | 71 |
Fresh compatible FastMCP 3.x resolution (3.4.11) | 70 |
Fresh current FastMCP 4.x resolution (4.2.0) | 64 |
Fresh current official SDK 2.x resolution (mcp 2.3.0) | 30 |
Original qkrun runtime including bundled MCP | 77 |
Updated qkrun runtime without MCP | 11 |
Standalone qkrun-mcp runtime, including qkrun 2.1 and SDK 2.3.0 | 39 |
Baseline: qkrun commit 7e8f3fd9276233955d713166d2ec5a015dfc82d7.
Fresh comparisons used uv pip compile --python-version 3.12 --universal
with fastmcp>=3.4,<4, fastmcp>=4.2,<5, and mcp>=2.3,<3, respectively.
The server uses the current SDK major (mcp>=2.3,<3); its lock resolves 2.3.0,
released on 2026-10-02 according to both official GitHub and PyPI metadata.
The dependency comparison and lock counts were rechecked on 2026-11-15.
Both projects are maintained: FastMCP is a full framework maintained by Prefect;
the official SDK is maintained by the MCP project. FastMCP adds useful automatic
schema generation, dependency injection, and client utilities but brings a
larger tree (authentication, keyring, file storage, CLI/watch facilities).
For this two-tool stdio server the official low-level SDK avoids that framework
layer at the cost of explicit tool schemas, dispatch, argument validation, and
request logging. The v2 API uses constructor on_* handlers, explicit request
contexts, snake-case SDK fields, and full SDK result objects. Since v2 no longer
automatically validates low-level tool arguments, jsonschema is an explicit
direct dependency (already part of the SDK's runtime closure); expected
application failures are returned as SDK error-flagged tool results.
The SDK still includes HTTP/authentication dependencies even for stdio; no
claim is made that this eliminates vulnerability maintenance.
The runner constrains Watchdog to 6.x: native macOS watcher regression tests failed or hung after upgrading to 7.1, while all 44 passed with 6.0.0. Other compatible dependencies and both lockfiles have been refreshed.
Sources: FastMCP, official SDK, FastMCP releases, SDK releases. SDK 2.3.0 release, official v2 migration guide.
Development
uv sync --dev --locked
uv run python -m pytest
uv run ruff check .
uv run ruff format --check .
uv buildAvailable Tools
2 toolslist_tasksARead-only
Discover available non-private tasks and their arguments. Returns project, project_root and tasks for every project, or only the selected project. Filter by invocation name or alias.
Inputs: filter, project.
run_taskB
Execute a discovered task in a subprocess. Streams stdout as info and stderr as warning notifications; returns exit_code, stdout and stderr. Supply stdin for interactive input. Select project when multiple projects are registered.
Inputs: task_name (required), args, stdin, project, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools map cleanly to a discover-then-execute workflow with no overlap: list_tasks only reads metadata, run_task only executes. An agent can unambiguously pick the right tool from the description.
Both names follow the same verb_noun snake_case pattern (list_tasks, run_task), using the shared 'task' noun. Fully predictable and consistent.
Two tools is thin but coherent for a narrow task-runner domain; there is no padding. However, with only a discovery and an execution tool, the surface feels minimal rather than well-scoped.
Core flow (discover tasks and their arguments, then run with stdin/stdout/stderr handling) is covered. Gaps remain: no way to cancel or kill a running task, check status of in-flight runs, or inspect a task's schema beyond the listing.
Maintenance
Related MCP Connectors
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
Discover and call AI agents via MCP. Supports A2A agents and platform agents with async tasks.
Build, test, publish, and run Kovca workflows from AI agents over remote MCP.
Start and manage Reason cloud coding agents, projects and sessions from any MCP client.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables agents to submit and manage persistent, dependency-aware task graphs with immutable artifacts, resource reservations, durable event streaming, and retryable process execution over MCP.12MIT
- FlicenseNot gradedqualityAmaintenanceEnables MCP clients to submit and monitor long-running Codex Desktop tasks asynchronously, with polling, approvals, Plan Mode workflows, diagnostics, and restart recovery.-
- FlicenseNot gradedqualityAmaintenanceEnables MCP clients to submit and manage durable, long-running Codex Desktop tasks asynchronously, with polling, approvals, Plan Mode workflows, retry safety, diagnostics, and recovery state.-
- FlicenseNot gradedqualityAmaintenanceEnables MCP clients and orchestrators to submit long-running Codex Desktop tasks, poll their status, handle approvals and Plan Mode workflows, and retrieve final reports with diagnostics and recovery.-