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를 호출할 수 있게 합니다.
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
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
Node.js >= 18
qodercli installed and signed in (qodercli login)
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 installAdd 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_PROXYand/orHTTPS_PROXYto 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가 없는 경우가 많음).
{
"mcpServers": {
"qodercli-mcp": {
"command": "node",
"args": ["/absolute/path/to/qodercli-mcp/src/index.js"],
"env": {
"QODERCLI_PATH": "/absolute/path/to/qodercli"
}
}
}
}ask-qoderParameter | Type | Description |
| string (required) | The task or question for qodercli / qodercli에 전달할 작업 또는 질문 |
| string | Working directory / 작업 디렉터리 |
| string | Model for this session; call |
| string | Reasoning effort level ( |
| enum |
|
| enum | codex-style: |
| enum |
|
| string | Replace the default system prompt / 기본 시스템 프롬프트 교체 |
| string | Append instructions to the default system prompt / 시스템 프롬프트에 추가 |
| string | Resume a previous session / 이전 세션 재개 |
| string | Passed to |
| string[] | Raw CLI args appended before the prompt; reserved flags (permission mode, system prompt, model, |
| number | Timeout in ms, default 600000 / 타임아웃(밀리초), 기본값 600000 |
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 | Effective permission mode / 실제 권한 모드 | Effect on qodercli / qodercli에 미치는 효과 |
(omitted / 생략) |
| Read-only: permission-requiring tools are silently denied / 읽기 전용: 권한이 필요한 도구 호출이 자동 거부됨 |
|
| Plus |
|
| Agent can create/modify files in |
|
| Full access including shell / 셸을 포함한 전체 액세스 |
Explicit permission_mode or approval_policy always wins over sandbox.
명시적으로 설정된 permission_mode / approval_policy가 sandbox보다 우선합니다.
Mode | Behavior / 동작 |
| Read-only: silently denies every tool call that requires permission. Headless-safe default / 읽기 전용: 권한이 필요한 모든 도구 호출을 자동 거부; 헤드리스 안전 기본값 |
| Auto-approves file edits; shell still governed by policy / 파일 편집 자동 승인; 셸은 정책에 따라 제어됨 |
| Auto-approves everything including shell / 셸 포함 모든 항목 자동 승인 |
| qodercli's own automatic policy / qodercli 자체 자동 정책 |
| Interactive confirmation — not headless-friendly, avoid in MCP calls / 대화형 확인 — 헤드리스에 적합하지 않음, MCP 호출에서 피해야 함 |
list-sessionsLists local qodercli sessions (index, summary, session id) so a client can
pick a resume_session_id. Takes no arguments.
로컬 qodercli 세션(인덱스, 요약, 세션 ID)을 나열하여 클라이언트가 resume_session_id를 선택할 수 있도록 합니다. 인수가 없습니다.
list-modelsLists 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 배열을 반환합니다. 인수가 없습니다.
{ "name": "ask-qoder", "arguments": {
"prompt": "Explain what main.py does",
"cwd": "/path/to/project",
"timeout_ms": 180000
}}결과는 파일 기능을 이해하는 데 도움이 되는 자연어 설명을 반환합니다.
{ "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가 보안 권장 사항과 개선 제안을 제공합니다.
// 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를 통해 다중 턴 대화형 반복 최적화가 가능합니다.
{ "name": "ask-qoder", "arguments": {
"prompt": "Analyze performance bottlenecks in utils.py",
"model": "qwen-max",
"permission_mode": "default",
"output_format": "text",
"timeout_ms": 240000
}}성능 분석 및 최적화 제안 시나리오에 적합합니다.
{ "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는 파일 쓰기 및 셸 도구를 비활성화하여 감사/리뷰 시나리오에 적합합니다.
{ "name": "ask-qoder", "arguments": {
"prompt": "Summarize the architecture of this project and identify key modules",
"cwd": "/workspaces/repo",
"timeout_ms": 420000,
"model": "qwen-plus"
}}대규모 프로젝트의 빠른 정리 및 아키텍처 이해에 적합합니다.
작업 디렉토리 지정 — 특정 프로젝트에서 작업할 때는 항상 cwd를 전달하세요.
操作特定项目时务必指定 cwd
타임아웃 보호 사용 — 복잡한 프롬프트의 경우 timeout_ms를 60분보다 짧게 명시적으로 설정하세요.
复杂任务设置 timeout_ms（建议 5–10 分钟），避免挂起
다중 턴 재개 — 컨텍스트를 반복하지 않고 resume_session_id를 사용하여 후속 질문을 연결하세요.
后续追问用 resume_session_id 续接会话，避免重复上下文
모델 선택 — 먼저 list-models를 호출하여 현재 지원되는 모델을 확인하세요. 심층 분석에는 더 큰 모델이 더 좋습니다.
先调 list-models 查询当前可用模型；深度分析建议选择大模型
권한 모드 — 서버 기본값은 읽기 전용(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 混用（后者优先生效）
변수 | 기본값 | 설명 |
|
| qodercli 바이너리 경로 / qodercli 二进制路径 |
|
| 기본 타임아웃 / 默认超时 |
|
| 호출당 stdout/stderr 용량 제한(MB, OOM 보호) / 单次调用输出上限（MB，防 OOM） |
|
| 호출자가 permission_mode/approval_policy/sandbox를 생략할 때의 기본 권한 모드입니다. 전체(YOLO) 액세스를 위해 |
| - | qodercli용 HTTP 프록시 URL / qodercli 的 HTTP 代理地址 |
| - | qodercli용 HTTPS 프록시 URL / qodercli 的 HTTPS 代理地址 |
npm test # smoke test: protocol handshake + tool invocation
node src/index.js # run the server manually (stdio)이것은 비공식적인 타사 도구입니다. Qoder와 제휴, 보증 또는 후원되지 않습니다. permission_mode: bypass_permissions를 주의해서 사용하십시오. 위임된 프롬프트는 대상 작업 디렉토리의 파일을 수정할 수 있습니다.
本项目为非官方第三方工具，与 Qoder 官方无关。请谨慎使用 bypass_permissions 权限模式——委托的任务可能修改目标工作目录中的文件。
MIT
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.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for qodercli (project to operate on). | |
| model | No | Model to use for this session (e.g. 'Auto', 'Ultimate', 'Qwen3.8-Max', 'Kimi-K3'). Call the list-models tool first to get the currently supported model names. | |
| prompt | Yes | The task or question for qodercli. | |
| sandbox | No | Sandbox level, codex-style: read-only = dont_ask + blocked write/shell tools; workspace-write = accept_edits (agent can create/modify files in cwd); danger-full-access = bypass_permissions. Ignored when permission_mode or approval_policy is set. Default (when omitted) is read-only. | |
| extra_args | No | Additional raw CLI arguments appended before the prompt. Flags with dedicated parameters (permission mode, system prompt, model, output format, resume, cwd) are rejected. | |
| timeout_ms | No | Timeout in ms (default: 600000). | |
| output_format | No | CLI output format passed to -o (default: json). | |
| system_prompt | No | Replace qodercli's default system prompt for this call. | |
| approval_policy | No | codex-style approval policy: untrusted->dont_ask (read-only), on-request->auto, never->bypass_permissions. Mutually exclusive with permission_mode. | |
| permission_mode | No | Permission mode (default: dont_ask). dont_ask = READ-ONLY (silently denies edits/shell); accept_edits = auto-approve file edits; bypass_permissions = full access incl. shell; auto = qodercli's automatic policy. Mutually exclusive with approval_policy; prefer the sandbox parameter instead. | |
| reasoning_effort | No | Reasoning effort level passed to --reasoning-effort (e.g. 'low', 'medium', 'high'); supported levels depend on the selected model. | |
| resume_session_id | No | Resume a previous qodercli session by its identifier. | |
| append_system_prompt | No | Append extra instructions to the default system prompt. |
| Name | Required | Description |
|---|---|---|
| content | Yes | The assistant's final answer. |
| is_error | Yes | |
| exit_code | No | |
| num_turns | No | |
| timed_out | Yes | |
| truncated | Yes | |
| session_id | No | qodercli session id for follow-ups. |
| duration_ms | No | |
| total_credits | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description explains it delegates to a local coding assistant and returns session_id for resumption, but does not disclose potential side effects like file modifications or shell access, leaving that to schema parameter descriptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences that front-load the core action, use cases, and the session/resume flow; no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 13-parameter tool with output schema, the description provides the essential high-level context (delegation, use cases, resume flow) but could mention prerequisites like listing models first; schema compensates for parameter details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 13 parameters with descriptions; the description adds no parameter syntax or format details beyond schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Delegate') and resource ('qodercli'), lists concrete use cases (second opinion, code review, coding task), and clearly distinguishes from sibling tools that list sessions/models.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clearly explains when to use (second opinion, code review, self-contained coding task) but doesn't mention when not to use or alternatives beyond implicit distinction from list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List models currently supported by qodercli. Use this before picking a model name for ask-qoder.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| models | Yes | Model names as an array. |
| content | Yes | Model names, one per line. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It states it lists models but does not disclose any behavioral traits such as read-only nature, authentication, or caching. However, the tool is simple and likely read-only, so the lack of disclosure is not critical but could be improved.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences, front-loading the purpose. The second sentence adds clear usage guidance. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there are no parameters and the tool is simple, the description is complete enough. It tells the agent what the tool does and when to use it. An output schema is present but not detailed in the description; however, for a list operation, the description is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, and schema description coverage is 100% (vacuously). The description does not need to add parameter meaning. Baseline for zero parameters is 4, and the description adds no unnecessary information about parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does: 'List models currently supported by qodercli.' It uses a specific verb ('List') and resource ('models supported by qodercli'). It also distinguishes from siblings by noting to use this before picking a model name for ask-qoder, implying ask-qoder is a different action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool: 'Use this before picking a model name for ask-qoder.' This gives clear context. It does not explicitly mention when not to use it, but given the tool's singular purpose, the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List local qodercli sessions (index + id + summary) so you can pick a resume_session_id for ask-qoder.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| content | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It accurately describes a read-only listing operation with no side effects, and adds the context that sessions are 'local' (client-side). For a simple tool with no parameters, this is adequate behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 14 words, front-loaded with the action and purpose. Every word earns its place; there is no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (zero parameters, presence of an output schema), the description is fully sufficient. It explains what the tool does, why it is used, and the sibling tools are simple. The output schema covers return values, and the description previews the key fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, and schema description coverage is trivially 100%. Per the guidelines, zero parameters justifies a baseline score of 4. The description does not need to add parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list', the resource 'local qodercli sessions', and the specific output fields (index + id + summary). It also explains the purpose: to pick a resume_session_id for ask-qoder, which distinguishes it from its siblings (ask-qoder and list-models).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'so you can pick a resume_session_id for ask-qoder', which tells the agent when to use this tool (before calling ask-qoder with a session ID). It does not mention when not to use it or provide alternatives, but the context is clear and sufficient for a simple list tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.4.2ask-qoderlist-modelslist-sessionsScored across 3 tools
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.
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.
Three tools is appropriate for a CLI wrapper MCP server, covering the core interactions (task execution, session management, model listing) without unnecessary bloat.
The tool set covers the essential workflows for qodercli: initiating tasks, resuming sessions, and selecting models. No obvious gaps for its intended purpose.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
MCP server exposing the Backtest360 engine API as tools for AI agents.
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
