Skip to main content
Glama
qodercli-mcp

qodercli-mcp

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를 통해 스트리밍합니다.

Related MCP server: github-copilot-cli-mcp-server

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

Parameter

Type

Description

prompt

string (required)

The task or question for qodercli / qodercli에 전달할 작업 또는 질문

cwd

string

Working directory / 작업 디렉터리

model

string

Model for this session; call list-models to discover available names / 이 세션에 사용할 모델, list-models로 사용 가능한 이름 확인

reasoning_effort

string

Reasoning effort level (--reasoning-effort), e.g. low/medium/high; depends on the model / 추론 강도, 모델에 따라 다름

permission_mode

enum

dont_ask (default, read-only) | accept_edits (auto-approve file edits) | bypass_permissions (full access incl. shell) | auto | default; mutually exclusive with approval_policy, prefer sandbox / approval_policy와 상호 배타적, sandbox 권장

approval_policy

enum

codex-style: untrusted→read-only | on-request→auto | never→full access / codex 스타일 승인 정책, 자동 매핑

sandbox

enum

read-only | workspace-write | danger-full-access (codex-style; controls the effective permission mode) / 실제 권한 수준 제어

system_prompt

string

Replace the default system prompt / 기본 시스템 프롬프트 교체

append_system_prompt

string

Append instructions to the default system prompt / 시스템 프롬프트에 추가

resume_session_id

string

Resume a previous session / 이전 세션 재개

output_format

string

Passed to -o (default json) / -o에 전달(기본 json). Note: non-json formats degrade structured output (session_id etc. become unavailable) / 비json 형식은 구조화된 출력을 저하시킴(session_id 등 사용 불가)

extra_args

string[]

Raw CLI args appended before the prompt; reserved flags (permission mode, system prompt, model, -o, -r, -w...) are rejected / 프롬프트 앞에 추가되는 원시 CLI 인수; 예약된 플래그는 거부됨

timeout_ms

number

Timeout in ms, default 600000 / 타임아웃(밀리초), 기본값 600000

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 / 샌드박스 매핑

sandbox

Effective permission mode / 실제 권한 모드

Effect on qodercli / qodercli에 미치는 효과

(omitted / 생략)

dont_ask

Read-only: permission-requiring tools are silently denied / 읽기 전용: 권한이 필요한 도구 호출이 자동 거부됨

read-only

dont_ask

Plus --disallowed-tools write_file,replace,run_shell_command as defense in depth / 추가로 --disallowed-tools write_file,replace,run_shell_command를 사용한 심층 방어

workspace-write

accept_edits

Agent can create/modify files in cwd / 에이전트가 cwd에서 파일 생성/수정 가능

danger-full-access

bypass_permissions

Full access including shell / 셸을 포함한 전체 액세스

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

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

Mode

Behavior / 동작

dont_ask

Read-only: silently denies every tool call that requires permission. Headless-safe default / 읽기 전용: 권한이 필요한 모든 도구 호출을 자동 거부; 헤드리스 안전 기본값

accept_edits

Auto-approves file edits; shell still governed by policy / 파일 편집 자동 승인; 셸은 정책에 따라 제어됨

bypass_permissions

Auto-approves everything including shell / 셸 포함 모든 항목 자동 승인

auto

qodercli's own automatic policy / qodercli 자체 자동 정책

default

Interactive confirmation — not headless-friendly, avoid in MCP calls / 대화형 확인 — 헤드리스에 적합하지 않음, MCP 호출에서 피해야 함

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

변수

기본값

설명

QODERCLI_PATH

qodercli

qodercli 바이너리 경로 / qodercli 二进制路径

QODERCLI_TIMEOUT_MS

600000

기본 타임아웃 / 默认超时

QODERCLI_MAX_OUTPUT_MB

50

호출당 stdout/stderr 용량 제한(MB, OOM 보호) / 单次调用输出上限(MB,防 OOM)

QODERCLI_DEFAULT_PERMISSION_MODE

dont_ask

호출자가 permission_mode/approval_policy/sandbox를 생략할 때의 기본 권한 모드입니다. 전체(YOLO) 액세스를 위해 bypass_permissions로 설정하세요. / 调用方未指定权限参数时的默认模式;设 bypass_permissions 即全开(YOLO)

HTTP_PROXY

-

qodercli용 HTTP 프록시 URL / qodercli 的 HTTP 代理地址

HTTPS_PROXY

-

qodercli용 HTTPS 프록시 URL / qodercli 的 HTTPS 代理地址

개발 / 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

Available Tools

3 tools
ask-qoderA

Delegate a task to qodercli (Qoder CLI), a local agentic coding assistant. Use it to get a second opinion, a code review, or to have Qoder perform a self-contained coding task in a given working directory. Returns structured output including session_id; pass it back as resume_session_id to continue the conversation.

Inputs: prompt (required), cwd, model, sandbox, +9 more. Returns: content, is_error, exit_code, num_turns, +5 more

list-modelsA

List models currently supported by qodercli. Use this before picking a model name for ask-qoder.

Inputs: no named parameters. Returns: models, content

list-sessionsA

List local qodercli sessions (index + id + summary) so you can pick a resume_session_id for ask-qoder.

Inputs: no named parameters. Returns: content

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: ask-qoder for delegating tasks, list-sessions for managing sessions, and list-models for model selection. No overlap in functionality.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (ask-qoder, list-sessions, list-models), making them predictable and easy to understand.

    Tool Count5/5

    Three tools is appropriate for a CLI wrapper MCP server, covering the core interactions (task execution, session management, model listing) without unnecessary bloat.

    Completeness5/5

    The tool set covers the essential workflows for qodercli: initiating tasks, resuming sessions, and selecting models. No obvious gaps for its intended purpose.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers