qwen-cli-mcp

로컬에 설치된 Qwen Code CLI에 코딩 작업을 위임하는 MCP 서버입니다.

자체 에이전트 복사본을 번들링하는 대신 실제 qwen 바이너리를 감싸므로, 모든 호출이 여러분의 qwen 인증, 모델, MCP 서버, 설정을 상속받습니다. 모델 스택에 대한 어떤 것도 여기서 중복되지 않으며, qwen을 업그레이드해도 서버는 표류하지 않습니다.

pi-cli-mcp의 형제 프로젝트 — 동일한 아키텍처, 동일한 원칙, 운전석에는 qwen이 있습니다. 권위 있는 설계 문서는 SPEC.md입니다.

주 에이전트(Claude Code, Cursor, pi 자체, 모든 MCP 클라이언트)가 작업을 qwen에 넘겨야 할 때 사용하세요: 다른 모델 계열의 두 번째 의견, 메인 컨텍스트 창 밖에 두고 싶은 조사, 또는 병렬 작업.

설치

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

Node ≥ 22와 PATH에 동작하는 qwen이 필요합니다 (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

넉넉한 timeout이 중요합니다: 실제 위임 작업은 몇 분 동안 실행될 수 있습니다.

다른 모든 MCP 클라이언트

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

서버 이름을 짧게 유지하세요(qwen): 모델이 보게 될 도구 이름의 일부가 됩니다.

⚠️ 기본 승인 모드는 yolo입니다. 위임은 대리인이 행동할 수 있을 때만 유용하므로, 이 서버는 기본적으로 전체 도구 승인으로 qwen을 시작합니다 — cwd 안에서, 여러분의 사용자로. QWEN_MCP_APPROVAL_MODE, 호출별 approval_mode, 또는 allowed_tools로 좁힐 수 있습니다. 분석 전용 작업에는 allowed_tools: "read,grep,ls" 스타일의 허용 목록을 전달하세요.

도구

qwen

반환되는 것

qwen의 최종 결과와 총계 통계만 반환됩니다 — 대화 기록, 도구 인자, 원시 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

답변은 qwen이 턴 끝에 내보내는 result 봉투입니다 — 답변 선택 추측이 없습니다. 오류 봉투(error_max_turns, error_during_execution)는 qwen이 말한 모든 것을 유지하면서 호출을 실패시키므로 작업은 재개 가능한 상태로 유지됩니다. 결과 봉투 없이 끝나는 스트림은 손상된 것으로 보고되며, 절대 원시 출력으로 조용히 대체되지 않습니다.

세션

qwen은 세션 ID를 반환하고, qwen_reply는 --resume으로 이를 재개합니다. 대화는 qwen 자체 세션 저장소에 있으므로, 후속 작업은 이 서버를 재시작해도 계속 동작합니다 — 세션 → 디렉터리 매핑은 ~/.local/state/qwen-mcp/sessions.json에 영속화됩니다.

한 세션에 대한 동시 응답은 서버 프로세스별로 직렬화됩니다: 하나의 세션 파일에 쓰는 두 개의 qwen 프로세스는 그 파일을 손상시킬 수 있습니다. 프로세스 간 주의사항: 두 MCP 클라이언트를 두 서버 프로세스에 연결하고 둘 다 동시에 동일한 세션 ID에 응답하면, 이를 직렬화하는 것이 없습니다. 실제로는 한 클라이언트가 세션을 소유합니다. 확실한 보장을 원하면 서버 프로세스를 하나로 유지하세요.

전송

stream이 기본값인 이유는 상위 집합이기 때문입니다: 동일한 메시지 스트림에 더해 실행 중인 턴이 계속 도달 가능하고 중단된 턴이 프로토콜 내에서 종료되어 스트림의 꼬리를 유지합니다. transport로 호출별로 선택하거나 QWEN_MCP_TRANSPORT=print로 기본값을 설정하세요.

이 서버는 스스로 qwen에 아무것도 보내지 않습니다. 마감 전 자동 마무리, 주입된 지시 없음: qwen_send는 호출자가 호출할 때만 발화합니다.

환경

설계

• 호출당 프로세스. Qwen 자체 세션 파일이 진실의 원천이며, 이것이 후속 작업이 이 서버의 재시작을 견디게 만드는 이유입니다.

• 유선 계약은 qwen 자체의 stream-json 프로토콜이며, 직접 말합니다 — stdout의 개행으로 구분된 메시지, stdin의 제어 요청과 사용자 턴. 그 형태는 @qwen-code/sdk에서 import type으로 차용하므로, 상류 변경은 서버가 아닌 빌드를 깨뜨립니다. 런타임 의존성 제로.

• qwen에서 오는 모든 것에 대해 실패 폐쇄. 알 수 없는 결과 하위 유형, 실패한 핸드셰이크, 파싱되지 않는 줄 — 모두 그렇게 보고되며 절대 성공으로 정규화되지 않습니다.

• 어떤 프로세스도 요청을 넘어 살아남지 않습니다. 타임아웃, 취소, 종료는 전체 qwen 프로세스 트리를 수확합니다; 어떤 경로에서도 아무것도 남지 않습니다.

개발

TypeScript(네이티브 tsc), Biome, Vitest. 테스트는 qwen의 프로토콜을 말하는 픽스처에 대해 stdio를 통해 실제 서버 바이너리를 구동합니다; 설치된 qwen에 대한 라이브 테스트는 선택 사항입니다.

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

라이선스

MIT