Ladder_mcp

Windows-first MCP bridge for the Kimi CLI (v24). It exposes Kimi Code as MCP tools so a client like Claude Code can run codebase analysis, native sessions, API queries, ACP chat, background tasks, and CLI admin/diagnostics — all on Windows without hardcoded POSIX assumptions.

Status: v1.1.6 (npm). Supported platform is Windows 11 only.

Highlights

• Agentic codegen & analysis — point Kimi at a repo to read or edit files.

• Two transports — persistent ACP JSON-RPC (default) with granular, watchable live progress and interactive permission prompts, or robust one-shot CLI. Pick one →

• Background tasks — kick off long runs and poll status/output, with a live TODO checklist surfaced as Kimi works.

• Independent review — kimi_ask runs stateless questions or a skeptical second-opinion review of supplied material (no repo access, no edits).

• Session-aware — list, inspect, and resume Kimi sessions across the CLI catalog and ACP.

• Diagnostics & setup — one call to check install/auth/health, one to emit the MCP config for a Kimi-hosted server.

• Windows-native — resolves kimi.exe, ~/.kimi-code, and PATH correctly; no POSIX assumptions.

Related MCP server: enhanced-filesystem-mcp

Requirements

• Windows 11

• Node.js ≥ 18

• Kimi Code CLI installed (kimi.exe on PATH or at ~/.kimi-code/bin/kimi.exe), authenticated (~/.kimi-code/)

Quick start (from npm)

You don't need to clone or build — the package is published on npm and your MCP client launches it via npx, or you can install the package directly.

Claude Code (one command):

claude mcp add kimi-code -- npx -y ladder-mcp

Or add it manually to your MCP config:

{
  "mcpServers": {
    "kimi-code": {
      "command": "npx",
      "args": ["-y", "ladder-mcp"]
    }
  }
}

Then in Claude Code run /mcp (should show kimi-code: connected) and call kimi_status to confirm the environment is detected.

The server speaks MCP over stdio: it is launched and managed by the client, not run by hand. Running npx ladder-mcp directly will appear to "hang" — that is the server correctly waiting for a client. Exit with Ctrl+C.

Prefer a global install? npm install -g ladder-mcp, then use ladder-mcp as the command instead of npx -y ladder-mcp.

Or install locally into your project:

npm install ladder-mcp

Then point your MCP config at ./node_modules/.bin/ladder-mcp (or use npx -y ladder-mcp, which resolves the locally installed copy when available).

To let Kimi Code itself host this server, use the kimi_setup tool to produce/merge a .kimi-code/mcp.json entry.

Tools

Core (always on)

* = required.

kimi_code supports both the ACP JSON-RPC transport (default) and the native CLI transport (transport: 'cli'); set background: true to track long work as a background task.

Experimental (off by default)

Enable with the environment variable LADDER_EXPERIMENTAL=1:

Transports: CLI vs ACP

Both transports can edit files and resume sessions; they differ in robustness and how much live progress you can watch.

Rule of thumb: stay on acp as the default for most work; reach for cli explicitly when you need the most robust one-shot process on Windows and can tolerate coarse progress reporting.

Background tasks

For long runs, set background: true on kimi_code. The call returns immediately with a task id; poll it with kimi_tasks:

// 1. start
kimi_code { "prompt": "...", "work_dir": "C:\\repo", "edit": true, "background": true }
// 2. watch — list all, or pass task_id for one
kimi_tasks { "action": "status", "task_id": "task_1" }
// 3. read the full accumulating transcript (TODO checklist + every action)
kimi_tasks { "action": "output", "task_id": "task_1" }
// 4. stop early (kills the Kimi child process)
kimi_tasks { "action": "cancel", "task_id": "task_1" }

Unlike the single overwriting live-progress line of a foreground call, the task log keeps the full transcript — every progress event and each TODO snapshot as Kimi maintains its plan.

Configuration

Environment variables

Timeouts

Every tool that drives Kimi accepts a timeout_ms override. Defaults: CLI kimi_code 10 min, ACP 2 min, kimi_ask 2 min (5 min in verify mode), API 5 min, CLI admin calls 30 s.

Safety boundaries

• edit defaults to false (analysis-only intent). On Kimi 0.20.1 the read-only guard for -p mode is prompt-enforced (advisory), as the CLI provides no hard read-only flag.

• kimi_export_session requires an explicit output_path, stays within the working directory, and excludes the global diagnostic log by default.

• Desktop Work tools are experimental and read-only: they do not read the desktop token store, replay web auth, or submit desktop Work tasks.

• The vendored kimi-code-mcp/ is a read-only reference and is never edited or written to by the tools.

Build from source (contributors)

npm install
npm run build      # compiles src/ -> dist/ (tests excluded)

Quick checks:

npm test           # vitest (175 tests)
npm run typecheck  # tsc --noEmit (incl. tests)
npm run dev        # run the server from source via tsx

Troubleshooting

• kimi-code not connected / tools missing — run kimi_status. It reports whether the binary, catalog, credentials, and config are found and whether the API is configured.

• npx ladder-mcp seems to hang — expected; it is the stdio server waiting for a client. It is meant to be launched by your MCP client, not by hand.

• kimi_ask errors about a missing key — set KIMICODE_API_KEY or add api_key to ~/.kimi-code/config.toml.

• Need maximum robustness for plain codegen — choose the explicit cli transport; acp is the default but is heavier and best reserved for watchable/interactive work.

Project layout

• src/ — the Ladder_mcp application (package ladder-mcp)

• kimi-code-mcp/ — upstream reference (read-only, MIT)

License

MIT. Ports logic from the MIT-licensed kimi-code-mcp reference.