qodercli-mcp

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

A minimal MCP server that wraps the local qodercli (Qoder CLI) into an MCP tool, allowing any MCP client (Qoder IDE, Claude Code, Cursor, etc.) to call Qoder like a sub-agent.

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-qoder tool — delegate a prompt to qodercli

• ask-qoder tool — delegate tasks to qodercli

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

• Structured output (session_id, is_error, duration_ms, total_credits, num_turns), automatically parsed from -o json

• list-sessions tool to discover resumable sessions

• list-sessions tool, used to discover resumable sessions

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

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

• reasoning_effort parameter (--reasoning-effort)

• reasoning_effort parameter (passes through --reasoning-effort)

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

• The MCP initialize result carries server usage instructions to guide clients on correct invocation

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

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

• System prompt injection (system_prompt / append_system_prompt)

• System prompt injection (system_prompt / append_system_prompt)

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

• Supports specifying working directory, model, permission mode, output format

• Session resume (resume_session_id) for multi-turn delegation

• Supports session resume (resume_session_id) for multi-turn delegation

• Timeout protection with SIGKILL fallback

• Timeout protection (automatic SIGKILL on timeout)

• Proxy quota support (HTTP_PROXY / HTTPS_PROXY injection)

• Proxy quota support (HTTP_PROXY / HTTPS_PROXY injection)

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

• No build step — pure 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.

"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

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.

{
  "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

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

Explicit permission_mode or approval_policy always wins over 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.

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 
}}

The result returns a natural language explanation to help understand the file's functionality.

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 will provide security suggestions and improvement plans.

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": {} }

Through resume_session_id, multi-turn interactive iterative optimization can be achieved.

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 
}}

Suitable for performance analysis and optimization suggestions.

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 file writing and shell tools, suitable for audit/review scenarios.

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"
}}

Suitable for quick understanding and architecture analysis of large projects.

Best Practices

1. Specify working directory — Always pass cwd when operating on a specific project Always specify cwd when operating on a specific project

2. Use timeout protection — For complex prompts, set explicit timeout_ms shorter than 60min For complex tasks, set timeout_ms (recommended 5–10 minutes) to avoid hangs.

3. Resume for multi-turn — Chain follow-ups via resume_session_id instead of repeating context Use resume_session_id to continue the conversation for follow-up questions, avoiding repeated context.

4. Model selection — Call list-models first to discover currently supported models; larger models are better for deep analysis Call list-models first to query currently available models; for deep analysis, it is recommended to choose a large model.

5. Permission mode — The server default is read-only (dont_ask); set QODERCLI_DEFAULT_PERMISSION_MODE=bypass_permissions to make full (YOLO) access the default for personal deployments. Per-call: tasks that must create/modify files need sandbox: "workspace-write"; shell access needs danger-full-access. Do not combine sandbox with an explicit permission_mode (the latter wins) The server defaults to read-only (dont_ask); for personal deployment, set QODERCLI_DEFAULT_PERMISSION_MODE=bypass_permissions to make full access (YOLO) the default. Per-call: to modify files, set sandbox: "workpace-write"; for shell access, use danger-full-access; do not mix with explicit permission_moie (the latter takes precedence).

Environment variables / environment variables

Development / development

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

Disclaimer / 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.

This project is an unofficial third-party tool and is not affiliated with Qoder. Please use bypass_permissions permission mode with caution — delegated tasks may modify files in the target working directory.

License

MIT