qodercli-mcp

A minimal MCP server that wraps qodercli (Qoder CLI), letting any MCP client delegate coding tasks to a local Qoder agent.

극소형 MCP 서버로, 로컬의 qodercli(Qoder CLI)를 MCP 도구로 래핑하여, 모든 MCP 클라이언트(Qoder IDE, Claude Code, Cursor 등)가 마치 하위 Agent를 호출하듯 Qoder를 호출할 수 있게 합니다.

Why / 왜

Some CLI agents ship an official MCP server mode (e.g. codex mcp-server), but qodercli currently only acts as an MCP client. This project fills that gap with a thin wrapper: it spawns qodercli -p <prompt> under the hood and streams the result back over MCP stdio.

일부 CLI Agent는 공식 MCP 서버 모드(예: codex mcp-server)를 제공하지만, qodercli는 현재 MCP 클라이언트로만 작동합니다. 이 프로젝트는 얇은 래퍼로 이 격차를 메웁니다: 내부적으로 qodercli -p <prompt>를 실행하고 결과를 MCP stdio를 통해 스트리밍합니다.

Features / 기능

• ask-qoder tool — delegate a prompt to qodercli

• ask-qoder 도구 — 작업을 qodercli에 위임

• Structured output (session_id, is_error, duration_ms, total_credits, num_turns) via -o json parsing

• 구조화된 출력(session_id, is_error, duration_ms, total_credits, num_turns), -o json 자동 파싱

• list-sessions tool to discover resumable sessions

• list-sessions 도구 — 재개 가능한 세션 탐색

• list-models tool for runtime model discovery (no stale model lists)

• list-models 도구 — 런타임 모델 탐색(오래된 목록 없음)

• reasoning_effort parameter (--reasoning-effort)

• reasoning_effort 매개변수(--reasoning-effort 전달)

• Server instructions in the MCP initialize result guide clients on usage

• MCP initialize 결과에 서버 사용 설명 포함, 클라이언트 안내

• Codex-style sandbox levels (read-only / workspace-write / danger-full-access)

• Codex 스타일 sandbox 수준(read-only / workspace-write / danger-full-access)

• System prompt injection (system_prompt / append_system_prompt)

• 시스템 프롬프트 주입(system_prompt / append_system_prompt)

• Working directory, model, permission mode, output format control

• 작업 디렉터리, 모델, 권한 모드, 출력 형식 제어 지원

• Session resume (resume_session_id) for multi-turn delegation

• 세션 재개(resume_session_id) — 다중 턴 위임 가능

• Timeout protection with SIGKILL fallback

• 타임아웃 보호(자동 SIGKILL 폴백)

• Proxy quota support (HTTP_PROXY / HTTPS_PROXY injection)

• 프록시 할당량 지원(HTTP_PROXY / HTTPS_PROXY 주입)

• Zero build step — plain ESM JavaScript, Node.js >= 18

• 빌드 불필요 — 순수 ESM JavaScript, Node.js >= 18

Prerequisites / 전제 조건

1. Node.js >= 18

2. qodercli installed and signed in (qodercli login)

Install / 설치

Option A — npx (recommended / 권장): no clone needed, the MCP client downloads the package on first use. 클론 불필요, MCP 클라이언트가 최초 사용 시 패키지를 자동 다운로드:

"command": "npx", "args": ["-y", "qodercli-mcp"]

Option B — from source (for development / 개발용):

git clone https://github.com/cantbeblank96/qodercli-mcp.git
cd qodercli-mcp
npm install

MCP client configuration / MCP 클라이언트 설정

Qoder IDE

Add to ~/.qoder/mcp.json. Prefer the absolute path of node and set QODERCLI_PATH explicitly (nvm-managed binaries are often missing from the PATH seen by MCP child processes):

Proxy Support: To use your Qoder CLI proxy quota, add HTTP_PROXY and/or HTTPS_PROXY to the server's environment. When these are set at the MCP server level, they will be passed to all qodercli subprocesses.

~/.qoder/mcp.json에 추가합니다. node의 절대 경로를 사용하고 QODERCLI_PATH를 명시적으로 설정하는 것이 좋습니다(MCP 자식 프로세스의 PATH에는 nvm으로 관리되는 바이너리가 없는 경우가 많음):

프록시 지원: Qoder CLI 프록시 할당량을 사용하려면 서버 환경에 HTTP_PROXY 및/또는 HTTPS_PROXY를 추가하세요. MCP 서버 수준에서 설정되면 모든 qodercli 하위 프로세스에 전달됩니다.

{
  "mcpServers": {
    "qodercli-mcp": {
      "command": "npx",
      "args": ["-y", "qodercli-mcp"],
      "env": {
        "QODERCLI_PATH": "/absolute/path/to/qodercli",
        "PATH": "/usr/local/bin:/usr/bin:/bin"
      }
    },
    "qodercli-mcp-with-proxy": {
      "command": "npx",
      "args": ["-y", "qodercli-mcp"],
      "env": {
        "QODERCLI_PATH": "/absolute/path/to/qodercli",
        "HTTP_PROXY": "http://127.0.0.1:39900",
        "HTTPS_PROXY": "http://127.0.0.1:39900",
        "PATH": "/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

Developers running a local checkout instead of the published package (Option B) should replace command/args with the absolute node path and /path/to/qodercli-mcp/src/index.js (nvm-managed node is often missing from the PATH seen by MCP child processes). 로컬 소스(방식 B)를 사용하는 개발자는 command/args를 node 절대 경로와 /path/to/qodercli-mcp/src/index.js로 바꾸세요(MCP 자식 프로세스의 PATH에는 nvm으로 관리되는 node가 없는 경우가 많음).

Claude Code / Claude Desktop

{
  "mcpServers": {
    "qodercli-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/qodercli-mcp/src/index.js"],
      "env": {
        "QODERCLI_PATH": "/absolute/path/to/qodercli"
      }
    }
  }
}

Tool: ask-qoder

Structured output / 구조화된 출력

ask-qoder declares an MCP outputSchema and returns, in addition to the human-readable text, a structuredContent object:

ask-qoder는 MCP outputSchema를 선언하며, 사람이 읽을 수 있는 텍스트 외에도 structuredContent 객체를 반환합니다:

{
  "session_id": "77826b5c-...",   // pass back as resume_session_id / 回传用于续接
  "content": "OK",
  "is_error": false,
  "exit_code": 0,
  "duration_ms": 1280,
  "total_credits": 0.53,
  "num_turns": 1,
  "timed_out": false,
  "truncated": false
}

Sandbox mapping / 샌드박스 매핑

Explicit permission_mode or approval_policy always wins over sandbox. 명시적으로 설정된 permission_mode / approval_policy가 sandbox보다 우선합니다.

Permission modes (verified semantics) / 권한 모드(검증된 의미)

Tool: list-sessions

Lists local qodercli sessions (index, summary, session id) so a client can pick a resume_session_id. Takes no arguments.

로컬 qodercli 세션(인덱스, 요약, 세션 ID)을 나열하여 클라이언트가 resume_session_id를 선택할 수 있도록 합니다. 인수가 없습니다.

Tool: list-models

Lists models currently supported by qodercli (via --list-models), so a client can pick a valid model value at runtime instead of relying on stale knowledge. Returns both a text list and a structured models array. Takes no arguments.

qodercli가 현재 지원하는 모델을 나열하여(--list-models 사용) 클라이언트가 오래된 지식에 의존하지 않고 런타임에 유효한 model 값을 선택할 수 있도록 합니다. 텍스트 목록과 구조화된 models 배열을 반환합니다. 인수가 없습니다.

Usage Examples / 사용 예시

Example 1: Simple code explanation / 간단한 코드 설명

{ "name": "ask-qoder", "arguments": { 
  "prompt": "Explain what main.py does",
  "cwd": "/path/to/project",
  "timeout_ms": 180000 
}}

결과는 파일 기능을 이해하는 데 도움이 되는 자연어 설명을 반환합니다.

Example 2: Ask a second opinion / 두 번째 의견 요청

{ "name": "ask-qoder", "arguments": { 
  "prompt": "@src/service.py Review this file for security issues and suggest improvements",
  "model": "qwen-plus",
  "permission_mode": "dont_ask",
  "timeout_ms": 300000 
}}

Qoder가 보안 권장 사항과 개선 제안을 제공합니다.

Example 3: Multi-turn conversation via resume / 재개를 통한 다중 턴 대화

// First call — session_id comes back in structuredContent
// 首次调用 —— session_id 会在 structuredContent 中返回
{ "name": "ask-qoder", "arguments": {
  "prompt": "Help me refactor this module to improve readability",
  "cwd": "/projects/backend",
  "timeout_ms": 300000 
}}
// Then reuse structuredContent.session_id:
// 然后把 structuredContent.session_id 回传：
{ "name": "ask-qoder", "arguments": {
  "prompt": "Now add error handling for database timeouts",
  "resume_session_id": "77826b5c-cd6b-4213-b423-d95b4e1deab0"
}}
// Or discover ids with list-sessions / 或用 list-sessions 查找历史会话 ID
{ "name": "list-sessions", "arguments": {} }

resume_session_id를 통해 다중 턴 대화형 반복 최적화가 가능합니다.

Example 4: Code review with specific focus / 특정 초점의 코드 리뷰

{ "name": "ask-qoder", "arguments": {
  "prompt": "Analyze performance bottlenecks in utils.py",
  "model": "qwen-max",
  "permission_mode": "default",
  "output_format": "text",
  "timeout_ms": 240000 
}}

성능 분석 및 최적화 제안 시나리오에 적합합니다.

Example 5: Read-only analysis / 읽기 전용 분석

{ "name": "ask-qoder", "arguments": {
  "prompt": "Audit this codebase for security issues; do not modify anything",
  "cwd": "/workspaces/repo",
  "sandbox": "read-only",
  "timeout_ms": 300000 
}}

read-only는 파일 쓰기 및 셸 도구를 비활성화하여 감사/리뷰 시나리오에 적합합니다.

Example 6: Project-wide analysis / 프로젝트 전체 분석

{ "name": "ask-qoder", "arguments": {
  "prompt": "Summarize the architecture of this project and identify key modules",
  "cwd": "/workspaces/repo",
  "timeout_ms": 420000,
  "model": "qwen-plus"
}}

대규모 프로젝트의 빠른 정리 및 아키텍처 이해에 적합합니다.

Best Practices / 모범 사례

1. 작업 디렉토리 지정 — 특정 프로젝트에서 작업할 때는 항상 cwd를 전달하세요. 操作特定项目时务必指定 cwd

2. 타임아웃 보호 사용 — 복잡한 프롬프트의 경우 timeout_ms를 60분보다 짧게 명시적으로 설정하세요. 复杂任务设置 timeout_ms（建议 5–10 分钟），避免挂起

3. 다중 턴 재개 — 컨텍스트를 반복하지 않고 resume_session_id를 사용하여 후속 질문을 연결하세요. 后续追问用 resume_session_id 续接会话，避免重复上下文

4. 모델 선택 — 먼저 list-models를 호출하여 현재 지원되는 모델을 확인하세요. 심층 분석에는 더 큰 모델이 더 좋습니다. 先调 list-models 查询当前可用模型；深度分析建议选择大模型

5. 권한 모드 — 서버 기본값은 읽기 전용(dont_ask)입니다. 개인 배포의 경우 QODERCLI_DEFAULT_PERMISSION_MODE=bypass_permissions로 설정하여 전체(YOLO) 액세스를 기본값으로 만들 수 있습니다. 단일 호출의 경우: 파일을 생성/수정해야 하는 작업은 sandbox: "workspace-write"가 필요하고, 셸 액세스는 danger-full-access가 필요합니다. sandbox를 명시적인 permission_mode와 혼합하지 마십시오(후자가 우선 적용됨). 服务器默认只读（dont_ask）；个人部署可用 QODERCLI_DEFAULT_PERMISSION_MODE=bypass_permissions 将全开（YOLO）设为默认。单次调用：需要改文件设 sandbox: "workspace-write"，需要 shell 用 danger-full-access；勿与显式 permission_mode 混用（后者优先生效）

환경 변수 / Environment variables

개발 / Development

npm test        # smoke test: protocol handshake + tool invocation
node src/index.js   # run the server manually (stdio)

면책 조항 / Disclaimer

이것은 비공식적인 타사 도구입니다. Qoder와 제휴, 보증 또는 후원되지 않습니다. permission_mode: bypass_permissions를 주의해서 사용하십시오. 위임된 프롬프트는 대상 작업 디렉토리의 파일을 수정할 수 있습니다.

本项目为非官方第三方工具，与 Qoder 官方无关。请谨慎使用 bypass_permissions 权限模式——委托的任务可能修改目标工作目录中的文件。

라이선스

MIT