Skip to main content
Glama
cantbeblank96

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.

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.

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

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

Parameter

Type

Description

prompt

string (required)

The task or question for qodercli

cwd

string

Working directory

model

string

Model for this session; call list-models to discover available names

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

enum

codex-style: untrusted→read-only | on-request→auto | never→full access

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). Note: non-json formats degrade structured output (session_id etc. become unavailable)

extra_args

string[]

Raw CLI args appended before the prompt; reserved flags (permission mode, system prompt, model, -o, -r, -w...) are rejected

timeout_ms

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)

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

workspace-write

accept_edits

Agent can create/modify files in cwd

danger-full-access

bypass_permissions

Full access including shell

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

default

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

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

Variable

Default

Description

QODERCLI_PATH

qodercli

Path to the qodercli binary / qodercli binary path

QODERCLI_TIMEOUT_MS

600000

Default timeout / default timeout

QODERCLI_MAX_OUTPUT_MB

50

Per-call stdout/stderr cap in MB (OOM protection) / per-call output cap in MB (OOM protection)

QODERCLI_DEFAULT_PERMISSION_MODE

dont_ask

Default permission mode when the caller omits permission_mode/approval_policy/sandbox; set bypass_permissions for full (YOLO) access / Default mode when the caller does not specify permission parameters; set bypass_permissions to enable full access (YOLO)

HTTP_PROXY

-

HTTP proxy URL for qodercli / qodercli HTTP proxy address

HTTPS_PROXY

-

HTTPS proxy URL for qodercli / qodercli HTTPS proxy address

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

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
cwdNoWorking directory for qodercli (project to operate on).
modelNoModel 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.
promptYesThe task or question for qodercli.
sandboxNoSandbox 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_argsNoAdditional raw CLI arguments appended before the prompt. Flags with dedicated parameters (permission mode, system prompt, model, output format, resume, cwd) are rejected.
timeout_msNoTimeout in ms (default: 600000).
output_formatNoCLI output format passed to -o (default: json).
system_promptNoReplace qodercli's default system prompt for this call.
approval_policyNocodex-style approval policy: untrusted->dont_ask (read-only), on-request->auto, never->bypass_permissions. Mutually exclusive with permission_mode.
permission_modeNoPermission 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_effortNoReasoning effort level passed to --reasoning-effort (e.g. 'low', 'medium', 'high'); supported levels depend on the selected model.
resume_session_idNoResume a previous qodercli session by its identifier.
append_system_promptNoAppend extra instructions to the default system prompt.

Output Schema

ParametersJSON Schema
NameRequiredDescription
contentYesThe assistant's final answer.
is_errorYes
exit_codeNo
num_turnsNo
timed_outYes
truncatedYes
session_idNoqodercli session id for follow-ups.
duration_msNo
total_creditsNo

TDQS

A4/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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

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

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
modelsYesModel names as an array.
contentYesModel names, one per line.

TDQS

A4.2/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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

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

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
contentYes

TDQS

A4.5/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 3 tool updatesv0.4.2
    • First observedask-qoder
    • First observedlist-models
    • First observedlist-sessions

TDQS

A4.4/5.0
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

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/cantbeblank96/qodercli-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server