Skip to main content

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)

Source distribution for qkrun-mcp 0.1.0
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)

Table of built distributions (wheels) for qkrun-mcp 0.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page