kimi-code-mcp

English | 中文說明

Delegate codebase analysis from Claude to Kimi Code (default model k3, CLI alias kimi-code/k3) — cut Claude-side token cost ~90%.

*Illustrative estimates — savings are on Claude tokens only and depend on the task; Kimi's subscription cost is separate. See Token Economics.

Quick start

# 1. Install the current Kimi Code CLI (macOS / Linux) and log in.
#    code.kimi.com/install.sh redirects to the archived Python kimi-cli. Do not use it.
curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash
kimi login

# Node.js >= 22.19.0 alternative:
# npm install -g @moonshot-ai/kimi-code

# This server runs ~/.local/bin/kimi only. The installer puts the binary in
# ~/.kimi-code/bin and adds that directory to your shell rc.
mkdir -p "$HOME/.local/bin"
ln -sfn "$HOME/.kimi-code/bin/kimi" "$HOME/.local/bin/kimi"

# 2. Install this MCP server (Node.js >= 18)
npm install -g kimi-mcp-server

Windows (PowerShell): irm https://code.kimi.com/kimi-code/install.ps1 | iex. The runner in this repo still expects the POSIX path ~/.local/bin/kimi, so link the installed kimi binary there the same way.

Project scope — commit .mcp.json at the repo root:

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

User scope (all projects, stored in ~/.claude.json, not ~/.claude/mcp.json):

claude mcp add --scope user --transport stdio kimi-code -- npx -y kimi-mcp-server

Run /mcp in Claude Code to verify — you should see kimi-code with 8 tools.

The MCP defaults to k3 and passes -m kimi-code/k3 on CLI calls. Override with the tool's model argument or KIMICODE_MODEL / KIMI_MODEL (argument wins). On CLI 2.4.1, kimi provider list prints Default model: … when a default is set. That value can differ from the MCP default. Switch inside the CLI with /model.

Related MCP server: Ollama MCP Server

How it works

1. Claude calls the kimi_analyze tool when a task needs bulk codebase reading.

2. MCP routes the request to Kimi Code (default -m kimi-code/k3) — Kimi reads the codebase from disk.

3. The result is piped back as a structured response — Claude acts on it with precise, targeted edits.

┌──────────────┐  stdio/MCP   ┌──────────────┐  subprocess   ┌──────────────┐
│  Claude Code │ ◄──────────► │ kimi-code-mcp│ ────────────► │ Kimi CLI     │
│  (conductor) │              │ (MCP server) │               │ (k3)         │
└──────────────┘              └──────────────┘               └──────────────┘

Two backends: API vs CLI

The server reaches Kimi two different ways, and each tool uses the one that fits its job. Knowing which is which tells you what you need to set up.

Run kimi_status any time to see which backends are live — it reports the API-configured state and the CLI install/auth state separately.

Guidelines for agents

If you are an AI agent (Claude Code, a subagent, etc.) deciding when to call these tools:

• Cross-check your own work before committing → kimi_verify. Paste the actual diff/code/claim plus the surrounding context (goal, constraints, signatures). Kimi sees only the context string — no repo, no session history. Vague context → useless review.

• Quick model-agnostic programming question → kimi_query. No codebase needed. Returns a different model's opinion.

• Need to understand a large/unfamiliar codebase → kimi_analyze with work_dir. Prefer this over reading 50 files yourself; it's ~10× cheaper in Claude tokens. Requires the CLI to be installed and logged in.

• Drill deeper after an analyze → kimi_resume with the returned session_id (the CLI session keeps its context; the window is the model's, not a fixed 256K).

• Don't know why a Kimi call failed → kimi_status first. "Not authenticated" on the CLI does not affect kimi_query/kimi_verify (those use the API).

• Keep outputs lean. The tool default is detail_level: normal. Pass summary for orientation; use detailed only when you need code snippets. Bigger output = more Claude tokens, defeating the purpose.

• Skip Kimi for small/single-file work — Claude reading directly is faster under ~10 files.

MCP server that connects Kimi Code (default model k3) with Claude Code — letting Claude orchestrate while Kimi handles the heavy reading.

What is Kimi Code?

Kimi Code is Moonshot AI's coding agent (terminal, IDE, and Kimi Code CLI). The CLI is the TypeScript package @moonshot-ai/kimi-code. Public docs list CLI 2.4.1 (2026-10-30). It reads and edits code, runs shell commands, searches files, and fetches web pages.

Model ids below are from the Kimi Code model page and the alias prefix shipped in CLI 2.4.1 (kimi-code/<id> for the managed provider). Context is plan-dependent ("up to").

This server rewrites only a short alias table before the call:

k2.7 is a leftover shortcut. It still sends kimi-for-coding (K2.8 Preview), not kimi-for-coding-highspeed. For any other id, the API wants the bare id and the CLI wants kimi-code/<id>. One model value cannot be both unless it is in the table above. Check kimi provider list or /model after login; a re-login can drop custom aliases.

Install from source

If you prefer to build locally instead of using the npm package:

git clone https://github.com/howardpen9/kimi-code-mcp.git
cd kimi-code-mcp && npm install && npm run build

{
  "mcpServers": {
    "kimi-code": {
      "command": "node",
      "args": ["/absolute/path/to/kimi-code-mcp/dist/index.js"]
    }
  }
}

Kimi Code API Setup

CLI login and the direct API key are separate. kimi login does not give kimi_query / kimi_verify a key.

Option 1: OAuth login (CLI tools)

kimi login

This is the device-code flow (same credentials as /login in the TUI). The CLI writes config, sessions, and OAuth under ~/.kimi-code/ (KIMI_CODE_HOME overrides that directory). Legacy data may still sit in ~/.kimi. After login, kimi provider list prints Default model: when one is set. It may not be kimi-code/k3. The managed provider id is managed:kimi-code.

mkdir -p "$HOME/.local/bin"
ln -sfn "$(command -v kimi)" "$HOME/.local/bin/kimi"

Option 2: API key (direct API tools)

Create a key in the Kimi Code console. The MCP checks KIMICODE_API_KEY, then KIMI_CODE_API_KEY, then KIMI_API_KEY. KIMI_BASE_URL overrides the endpoint (default https://api.kimi.com/coding/v1; overseas coding host is https://api.kimi.ai/coding/v1).

# ~/.zshrc or ~/.bashrc — this process must see it (Claude's MCP env, not only an interactive shell)
export KIMICODE_API_KEY="sk-your-api-key"
# export KIMI_BASE_URL="https://api.kimi.ai/coding/v1"

The CLI does not read KIMICODE_API_KEY from the environment. For the CLI, use kimi login, or set api_key / api_key_env in ~/.kimi-code/config.toml. The MCP does not read api_key_env. It does expand ${VAR} inside a quoted api_key when it parses TOML.

Config search order: $KIMI_SHARE_DIR/config.toml (if set), ~/.kimi/config.toml, then ~/.kimi-code/config.toml. Only api_key and base_url under a [providers.*] table are used. default_model and the [models.*] table do not change the MCP's model.

If you keep the key in the file instead of the environment, the current CLI shape is:

default_model = "kimi-code/k3"

[providers."managed:kimi-code"]
type = "kimi"
base_url = "https://api.kimi.com/coding/v1"
api_key = "sk-your-api-key"

Do not paste that over a file kimi login already manages. An empty api_key = "" plus an oauth table is normal after login and is not a key this MCP can use. Prefer KIMICODE_API_KEY for the API tools.

Kimi Code vs Kimi Platform

What You Can Do

Just tell Claude what you need. It will delegate to Kimi automatically:

Why This Exists

Claude Code is powerful but expensive. Every file it reads costs tokens. Meanwhile, many tasks — pre-reviewing large codebases, scanning for patterns, generating audit reports — are high-certainty work that doesn't need Claude's full reasoning power.

How It Saves Tokens

                          ┌─────────────────────────────┐
                          │   You (the developer)       │
                          └──────────┬──────────────────┘
                                     │ prompt
                                     ▼
                          ┌─────────────────────────────┐
                          │   Claude Code (conductor)   │
                          │   - orchestrates workflow    │
                          │   - makes decisions          │
                          │   - writes & edits code      │
                          └──────┬──────────────┬───────┘
                      precise    │              │  delegate
                      edits      │              │  bulk reading
                      (tokens)   │              │  (Kimi plan)
                                 ▼              ▼
                          ┌──────────┐   ┌──────────────┐
                          │ your     │   │  Kimi Code   │
                          │ codebase │   │  - model k3  │
                          └──────────┘   │  - reads all │
                                         │  - reports   │
                                         └──────────────┘

1. Claude receives your task → decides it needs codebase understanding

2. Claude calls kimi_analyze via MCP → Kimi reads the codebase (subscription cost, not Claude tokens)

3. Kimi returns a structured analysis

4. Claude acts on the analysis with precise, targeted edits

Result: Claude only spends tokens on decision-making and code writing, not on reading files.

Mutual Code Review with Kimi Code

The default model is k3 (K3). That is enough context for AI pair review:

1. Kimi pre-reviews — one pass over the tree: security issues, anti-patterns, dead code, architectural problems

2. Claude cross-examines — reviews Kimi's findings, challenges questionable items, adds its own insights

3. Two perspectives — different models catch different things. What one misses, the other finds

Use Kimi as a Code Reviewer

Beyond ad-hoc analysis, you can use Kimi as a dedicated reviewer in your workflow:

PR Review Workflow

┌──────────────┐   diff    ┌──────────────┐  structured  ┌──────────────┐
│   Your PR    │ ────────► │  Kimi Code   │  findings    │  Claude Code │
│  (changes)   │           │  (reviewer)  │ ────────────►│  (decision)  │
└──────────────┘           └──────────────┘              └──────────────┘

Continuous Audit Pattern

Each review session can be resumed (kimi_resume) if you have its CLI session id. Context follows that session's model window.

What Kimi Reviews Well

Tools

Output Control Parameters

kimi_analyze and kimi_resume support these parameters to control output size:

kimi_query also supports max_output_tokens and include_thinking.

Token Economics

                    Without kimi-code-mcp        With kimi-code-mcp (normal)
                    ─────────────────────        ───────────────────────────
Raw source:         50 files × ~4K = 200K        Kimi reads (subscription cost)
Claude reads:       200K tokens                  5-15K token report
Claude token cost:  $$$                          $

Compression ratio by detail_level:

When savings happen:

• Large codebases (50+ files) — architecture understanding, cross-file scanning

• Security audits, dead code detection, API consistency checks

• Pre-review before targeted edits (scan first → edit specific files)

When to skip and let Claude read directly:

• Small codebases (<10 files) — direct reading is faster

• Single-file modifications — Claude's built-in file reading is sufficient

• When you need every line of code — detailed output approaches raw reading cost

Implementation details

Under the hood:

1. Claude Code calls an MCP tool (e.g., kimi_analyze)

2. This server spawns the kimi CLI with the prompt and codebase path

3. Kimi reads files and analyzes the code (context is the model window; default k3 is up to 1M on eligible plans)

4. The result is parsed from Kimi's JSON output and returned to Claude Code

5. Claude acts on the structured results — edits, plans, or further analysis

CLI Invocation Reference

The MCP server runs ~/.local/bin/kimi, reads kimi --help, and calls that binary in non-interactive mode. The flags below match the Kimi Code CLI command reference through 2.4.1 (2026-10-30):

cd <path>
kimi -m kimi-code/k3 -p "<prompt>" --output-format stream-json

Legacy CLI options --print, --final-message-only, and --no-thinking are sent only when advertised by that binary's help. Kimi Code 2.x does not support these flags or --work-dir; thinking=false is therefore only applied on supporting legacy CLIs. Do not combine --plan with -p.

If Kimi reports Stored token ... was rejected; re-login required, run kimi login. Local model catalog checks do not verify OAuth validity or remaining quota.

After re-login, custom aliases such as subscription-peer/kimi may disappear. Check kimi provider list and update any explicit model, KIMICODE_MODEL, or KIMI_MODEL override to an available alias. The MCP already defaults to the official kimi-code/k3 alias; it does not require the helper's custom alias.

In-repo tests fixture the 2.1.1 JSONL shape (a minimal K3 prompt returned KIMI_OK after re-login). They were not re-run against the 2.4.1 binary for this doc update. Flag selection still comes from kimi --help, so --print, --final-message-only, and --no-thinking are sent only when that help text lists them.

kimi_status marks the CLI authenticated only when it finds tokens in $KIMI_SHARE_DIR or ~/.kimi/credentials/kimi-code.json (or a legacy ~/.kimi/kimi.json). CLI 2.x stores OAuth under ~/.kimi-code/credentials/ (KIMI_CODE_HOME). A working kimi login can still show "Not authenticated" there. That does not affect kimi_query / kimi_verify.

kimi_list_sessions reads $KIMI_SHARE_DIR/sessions or ~/.kimi/sessions (metadata.json). Current sessions live in ~/.kimi-code/sessions/<workDirKey>/<sessionId>/ and are not listed. kimi_resume still passes -S <id> through, so an id you already have from the CLI can be resumed.

Advanced Setup

For development (auto-recompile on changes):

{
  "mcpServers": {
    "kimi-code": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/kimi-code-mcp/src/index.ts"]
    }
  }
}

npm

Published as kimi-mcp-server on npm. The registry copy checked on 2026-11-02 is 0.3.0; this tree is 0.5.0.

npx kimi-mcp-server            # registry build, currently 0.3.0
npm install -g kimi-mcp-server

Project Structure

src/
├── index.ts           # MCP server setup, tool definitions, API-vs-CLI routing
├── kimi-api.ts        # Direct Kimi Code API client (kimi_query / kimi_verify)
├── kimi-runner.ts     # Spawns kimi CLI, parses output, handles timeouts
├── cache-manager.ts   # Session cache (warmup, reuse, invalidation)
└── session-reader.ts  # Legacy session metadata (~/.kimi/sessions, not ~/.kimi-code)

Contributing

See CONTRIBUTING.md for guidelines.

Changelog

See CHANGELOG.md for version history.

License

MIT