qodercli-mcp
qodercli-mcp
English | 简体中文
The missing MCP server mode for Qoder CLI — delegate coding tasks to local Qoder agents from any MCP client (Qoder IDE, Claude Code, Cursor…).
A minimal MCP server that wraps the local qodercli (Qoder CLI) as MCP tools, letting any MCP client (Qoder IDE, Claude Code, Cursor, …) call Qoder like a sub-agent.

30s demo: MCP client ⇄ qodercli-mcp ⇄ qodercli — initialize → tools/list → list-models (real output, not sped up)
Quick start
Zero-config via npx — add this to your MCP client config (~/.qoder/mcp.json, claude_desktop_config.json, …):
{ "mcpServers": { "qodercli-mcp": { "command": "npx", "args": ["-y", "qodercli-mcp"] } } }Three tools are exposed:
Tool | Purpose |
| Delegate a task to qodercli |
| Discover resumable sessions |
| Runtime model discovery |
Highlights: verified permission semantics (see below — e.g. dont_ask is read-only),
codex-style sandbox/approval_policy, structured output (session_id/duration_ms/total_credits).
Full configuration options are in Install.
Related MCP server: github-copilot-cli-mcp-server
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.
Features
ask-qodertool — delegate a prompt to qodercliStructured output (
session_id,is_error,duration_ms,total_credits,num_turns) via-o jsonparsinglist-sessionstool to discover resumable sessionslist-modelstool for runtime model discovery (no stale model lists)reasoning_effortparameter (--reasoning-effort)Server
instructionsin the MCP initialize result guide clients on usageCodex-style
sandboxlevels (read-only/workspace-write/danger-full-access)System prompt injection (
system_prompt/append_system_prompt)Working directory, model, permission mode, output format control
Session resume (
resume_session_id) for multi-turn delegationTimeout protection with SIGKILL fallback
Proxy quota support (
HTTP_PROXY/HTTPS_PROXYinjection)Zero build step — plain ESM JavaScript, Node.js >= 18
Prerequisites
Node.js >= 18
qodercliinstalled and signed in (qodercli login)
Install
Option A — npx (recommended): no clone needed, the MCP client downloads the package on first use.
"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 installMCP client configuration
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_PROXYand/orHTTPS_PROXYto the server's environment. When these are set at the MCP server level, they will be passed to all qodercli subprocesses.
{
"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).
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 |
| string (required) | The task or question for 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 |
Structured output
ask-qoder declares an MCP outputSchema and returns, in addition to the
human-readable text, a structuredContent object:
{
"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 |
(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 modes (verified semantics)
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 |
| Interactive confirmation — not headless-friendly, avoid in MCP calls |
Tool: list-sessions
Lists local qodercli sessions (index, summary, session id) so a client can
pick a resume_session_id. Takes no arguments.
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.
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
}}Example 3: Multi-turn conversation via resume
// First call — session_id comes back in 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:
{ "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
{ "name": "list-sessions", "arguments": {} }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 disables write/shell tools — good for audits and reviews.
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
Specify working directory — Always pass
cwdwhen operating on a specific projectUse timeout protection — For complex prompts, set explicit
timeout_msshorter than 60minResume for multi-turn — Chain follow-ups via
resume_session_idinstead of repeating contextModel selection — Call
list-modelsfirst to discover currently supported models; larger models are better for deep analysisPermission mode — The server default is read-only (
dont_ask); setQODERCLI_DEFAULT_PERMISSION_MODE=bypass_permissionsto make full (YOLO) access the default for personal deployments. Per-call: tasks that must create/modify files needsandbox: "workspace-write"; shell access needsdanger-full-access. Do not combinesandboxwith an explicitpermission_mode(the latter wins)
Environment variables
Variable | Default | Description |
|
| Path to the qodercli binary |
|
| Default timeout |
|
| Per-call stdout/stderr cap in MB (OOM protection) |
|
| Default permission mode when the caller omits permission_mode/approval_policy/sandbox; set |
| - | HTTP proxy URL for qodercli |
| - | HTTPS proxy URL for qodercli |
Development
npm test # smoke test: protocol handshake + tool invocation
node src/index.js # run the server manually (stdio)Disclaimer
This is an unofficial, third-party tool. It is not affiliated with, endorsed, or sponsored by Qoder. Use permission_mode: bypass_permissions with care — delegated prompts may modify files in the target working directory.
Product Hunt Gallery
Main gallery image (1270×760, dark tech theme): ph-gallery.png. Optional demo video can be converted from the GIF (docs/demo.gif).
License
MIT
Available Tools
3 toolsask-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
Scored 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.
Maintenance
Related MCP Connectors
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Related MCP Servers
- AlicenseAqualityBmaintenanceLocal MCP server that wraps the headless Claude Code CLI as MCP tools, providing stateless access to Claude's coding capabilities through prompt-based interactions. It enables users to execute Claude Code commands with various prompt formats and structured outputs directly from MCP clients.3MIT
- AlicenseAqualityDmaintenanceWraps GitHub Copilot CLI as an MCP server, enabling MCP clients to run Copilot conversations for code tasks with support for session resumption and permission modes.4MIT
- FlicenseAqualityDmaintenanceProvides a secure interface to run Anthropic's Claude Code CLI as an MCP server, enabling task execution, persistent memory, and integration with MCP-enabled IDEs.12-
- AlicenseAqualityAmaintenanceA local MCP server that delegates coding tasks to a temporary OpenCode session and returns a completion report with changed files, tool calls, cost, and the subagent's reply.1523 npm1MIT