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/_qk
Built wheels declare the portable qkrun>=2.1,<3 dependency and never embed
local source paths.
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 uv.lock, FastMCP 3.4.2 closure |
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 build
Metadata
Release files for qkrun-mcp 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| qkrun_mcp-0.1.0.tar.gz | 109.2 kB | Without provenance | Details for qkrun_mcp-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| qkrun_mcp-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for qkrun_mcp-0.1.0-py3-none-any.whl |
Total release size: 121.7 kB
Release files / qkrun_mcp-0.1.0.tar.gz
| Download URL | qkrun_mcp-0.1.0.tar.gz |
|---|---|
| Size | 109.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fe44a927eaa483b4a15d62e3ab93e8ca81dc40f3d22e94034126c05928d1f313
|
|
BLAKE2b-256 checksum How to use checksums |
54886eb70d398dc64b4efb0c57d4af1b9ec3d65caf03867b56ca22442b5cbb9a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.13
|
Release files / qkrun_mcp-0.1.0-py3-none-any.whl
| Download URL | qkrun_mcp-0.1.0-py3-none-any.whl |
|---|---|
| Size | 12.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1a051a8de13bfbd5e1af3635abe5456fef864ebbf64a8c776510ac63f4820ce5
|
|
BLAKE2b-256 checksum How to use checksums |
0a86f5746fc5613a7eac8ed0151790df0a1b4ec847392e60619d186d055d201a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.13
|
Security for qkrun-mcp 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.