Qwen Cli

MCP server that delegates coding tasks to your locally installed Qwen Code CLI.

It wraps the real qwen binary instead of bundling its own copy of the agent, so every call inherits your qwen auth, models, MCP servers and settings. Nothing about your model stack is duplicated here, and the server does not drift when you upgrade qwen.

Sibling of pi-cli-mcp — same architecture, same principles, qwen behind the wheel. The authoritative design document is SPEC.md.

Use it when your primary agent (Claude Code, Cursor, pi itself, any MCP client) should hand work to qwen: a second opinion from a different model family, an investigation you want kept out of the main context window, or parallel work.

Install

npx -y qwen-cli-mcp         # no install
npm install -g qwen-cli-mcp # or global

Requires Node ≥ 22 and a working qwen on PATH (npm i -g @qwen-code/qwen-code).

Claude Code

claude mcp add-json qwen -s user '{
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "qwen-cli-mcp"],
  "timeout": 3600000
}'
claude mcp list | grep '^qwen:'    # expect: ✔ Connected

The generous timeout matters: a real delegated task can run for minutes.

Any other MCP client

{
  "mcpServers": {
    "qwen": { "command": "npx", "args": ["-y", "qwen-cli-mcp"] }
  }
}

Keep the server name short (qwen): it becomes part of the tool names your model sees.

⚠️ Default approval mode is yolo. Delegation is only useful when the delegate can act, so this server starts qwen with full tool approval by default — inside cwd, as your user. Narrow it with QWEN_MCP_APPROVAL_MODE, per-call approval_mode, or allowed_tools. For analysis-only work pass allowed_tools: "read,grep,ls"-style allowlists.

Tools

Tool	Purpose
qwen	Start a session. Returns [session: <uuid>], the result, and stats.
qwen_reply	Continue a finished or interrupted session — including one killed by a timeout.
qwen_models	List models qwen can actually reach right now (live probe via the control plane).
qwen_send	Deliver into a turn executing right now (abort / steer / follow_up; stream transport only).
qwen_running	List turns executing right now that qwen_send can reach.
qwen_sessions	List known sessions, newest first, with their working directory.

qwen

Argument	Notes
prompt	Required. Must be self-contained — qwen cannot see your conversation.
cwd	Absolute path; defaults to this server's cwd.
model	-m value. Defaults to qwen's own settings; qwen_models lists valid values.
approval_mode	plan | default | auto-edit | auto | yolo. Server default: see the warning above.
allowed_tools	Comma-separated tool allowlist passed as --allowed-tools.
effort	low … max reasoning effort. Stream transport only — qwen has no CLI flag for it.
system_prompt_append	Appended to qwen's system prompt for this run.
transport	stream (default) or print. Usually omit.
timeout_ms	Wall clock for this run. A run killed at the deadline stays resumable via qwen_reply.

What comes back

Only qwen's final result plus aggregate stats — never the transcript, tool arguments or raw stdout:

[session: 0927adc5-a840-4b68-93ca-5ca344c9fafb]

Refactored retry() in src/http.rs; all 12 tests pass.

---
qwen: qwen3-coder-plus · 6 turns · 5 tool calls: bash×2, read×2, edit · 18k in / 310 out · 41s

The answer is the result envelope qwen emits at the end of a turn — there is no answer-selection guesswork. An error envelope (error_max_turns, error_during_execution) fails the call while keeping everything qwen managed to say, so the work stays resumable. A stream that ends without any result envelope is reported as broken, never silently replaced by raw output.

Sessions

qwen returns a session id; qwen_reply resumes it with --resume. The conversation lives in qwen's own session store, so follow-ups keep working across restarts of this server — the session → directory map is persisted in ~/.local/state/qwen-mcp/sessions.json.

Concurrent replies to one session are serialized per server process: two qwen processes writing one session file would corrupt it. Cross-process caveat: if you run two MCP clients against two server processes and both reply to the same session id at the same time, nothing serializes them. In practice one client owns a session; for a hard guarantee, keep one server process.

Transports

	stream (default)	print
command	--input-format stream-json --output-format stream-json	-p --output-format stream-json
process	stays up, speaks the control plane on stdin	one process per turn, exits when done
mid-run delivery	qwen_send (interrupt / steer / follow_up)	impossible: qwen reads nothing while working
deadline / cancel	qwen's own interrupt first, signals only as fallback	SIGTERM, then SIGKILL

stream is the default because it is a superset: the same message stream, plus a running turn stays reachable and an interrupted one is ended in-protocol, keeping the tail of the stream. Pick per call with transport, or set the default with QWEN_MCP_TRANSPORT=print.

This server never sends anything into qwen on its own. No automatic wrap-up before a deadline, no injected instructions: qwen_send fires only when the caller calls it.

Environment

Variable	Default	Meaning
QWEN_MCP_BIN	qwen	Path to the qwen binary.
QWEN_MCP_APPROVAL_MODE	yolo	Default approval mode for every call. See the warning above.
QWEN_MCP_MODEL	unset	Default model for every call.
QWEN_MCP_TRANSPORT	stream	Default transport: stream or print.
QWEN_MCP_TIMEOUT_MS	1800000	Default wall clock; timeout_ms overrides it per call.
QWEN_MCP_MAX_TIMEOUT_MS	86400000	Ceiling on what timeout_ms may ask for.
QWEN_MCP_MAX_CONCURRENT	4	Concurrent qwen processes.
QWEN_MCP_MAX_OUTPUT	unset	Cap on the answer. Unset means no truncation.
QWEN_MCP_STDERR_LIMIT	1500	stderr tail included in the response.
QWEN_MCP_STDERR_KEEP_EVENTS	unset	1 forwards stderr verbatim, protocol lines included.
QWEN_MCP_MAX_CAPTURE	16000000	Read-buffer guard against a runaway stream.
QWEN_MCP_MAX_LINE	8000000	Longest single message line from qwen before it is dropped.
QWEN_MCP_MAX_FRAME	8000000	Longest single JSON-RPC frame from the client.
QWEN_MCP_MAX_SESSIONS	200	Remembered sessions before the oldest is dropped.
QWEN_MCP_KILL_GRACE_MS	5000	SIGTERM → SIGKILL grace period.
QWEN_MCP_INTERRUPT_GRACE_MS	5000	How long interrupt gets before signals (stream only).
QWEN_MCP_INIT_TIMEOUT_MS	15000	Initialize-handshake timeout (stream only).
QWEN_MCP_MODELS_TIMEOUT_MS	60000	Whole-run budget for the qwen_models probe.
QWEN_MCP_STATE	~/.local/state/qwen-mcp/sessions.json	Session → cwd map.
QWEN_MCP_WRAP	unset	Command prefix, e.g. a sandbox wrapper around qwen.

Design

• Process per call. Qwen's own session files are the source of truth, which is what makes follow-ups survive a restart of this server.
• The wire contract is qwen's own stream-json protocol, spoken directly — newline-delimited messages on stdout, control requests and user turns on stdin. Its shapes are borrowed from @qwen-code/sdk through import type, so an upstream change breaks the build instead of the server. Zero runtime dependencies.
• Fail closed on anything from qwen. An unknown result subtype, a failed handshake, a line that does not parse — reported as such, never normalized into success.
• No process outlives its request. Timeouts, cancellations and shutdown reap the whole qwen process tree; nothing is left behind on any path.

Development

TypeScript (native tsc), Biome, Vitest. Tests drive the real server binary over stdio against a fixture that speaks qwen's protocol; live tests against the installed qwen are opt-in.

npm run hooks          # once per clone: git hooks from .githooks/
npm run build          # tsc -> dist/
npm test               # unit + type tests, no API access, no tokens
npm run test:live      # 4 live tests against the real qwen binary (spends tokens)
npm run check          # format + types + tests
npm run fix            # biome --write

License

MIT