Kimi MCP Server — AI-to-AI Code Consultation Bridge

中文版 (Chinese)

What is This?

Kimi MCP Server is an MCP (Model Context Protocol) bridge that lets Claude Code consult Kimi (another AI model) as a read-only code analyst with web research capabilities. Think of it as giving Claude a "second opinion" — when facing complex design decisions, tricky bugs, or architectural trade-offs, Claude can ask Kimi to independently read the codebase and search the web for relevant context (documentation, known issues, best practices), then bring those findings back to you.

Why Build This?

Single-model AI coding assistants have blind spots. When Claude is deep in a debugging session or designing an architecture, it can develop tunnel vision — fixating on one approach while missing alternatives. This project addresses that by:

Breaking echo chambers — A second model reading the same code independently often catches what the first one missed
Structured disagreement — Instead of vague "review this" requests, each consultation has a specific role (skeptic, architect, debugger, judge) with structured input/output schemas, forcing rigorous analysis
Read-only safety — Kimi can read files and access the web, but it cannot execute commands, write files, or modify anything. Sensitive files (.env, credentials, keys) are explicitly blocked at the system prompt level
Evidence-based responses — Every consultation returns which files Kimi read and which web searches it performed, so you can verify the analysis is grounded in real code and up-to-date information, not hallucination

Design Philosophy

┌──────────────────────────────────────────────────────────┐
│  "Don't trust one model's opinion — get a second read."  │
└──────────────────────────────────────────────────────────┘

The core design principles:

Structured over freeform — Each role has a defined context schema. No "just look at this code" — you must specify what you're asking, what you've tried, and what constraints exist. This forces the caller (Claude) to organize its thinking before consulting.
Read-only by design — The Kimi agent is configured with ReadFile, Glob, Grep (code), and SearchWeb, FetchURL (web). No write, no exec. This is enforced at both the agent config level and the system prompt level.
Transparent evidence chain — The response includes evidence (list of files Kimi read with tool traces) and parse_ok (whether the structured output parsed correctly). If parse_ok is false, you know something went wrong.
Fail-safe over fail-silent — Retryable errors (exit code 75) are surfaced as retryable. Parse failures return the raw response preview so the caller can still extract value. The incomplete_trace flag warns when tool call/result pairs are missing.

Architecture

┌─────────────┐     MCP/stdio      ┌──────────────────┐    spawn     ┌──────────┐
│ Claude Code │ ◄──────────────►   │ kimi-mcp-server  │ ──────────►  │ Kimi CLI │
│  (client)   │                    │                  │   stdin/out  │ (agent)  │
└─────────────┘                    └──────────────────┘              └──────────┘
                                          │                               │
                                   ┌──────┴──────┐                 ┌─────┴──────┐
                                   │ Components: │                 │ Can:       │
                                   │• server.ts  │                 │• ReadFile  │
                                   │• kimi-client│                 │• Glob      │
                                   │• prompt-    │                 │• Grep      │
                                   │  builder    │                 │• SearchWeb │
                                   │• response-  │                 │• FetchURL  │
                                   │  parser     │                 │            │
                                   └─────────────┘                 │ Cannot:    │
                                                                   │• Write     │
                                                                   │• Execute   │
                                                                   └────────────┘

Data flow:

Claude Code calls the consult_kimi MCP tool with a role, message, and structured context
server.ts validates the input against role-specific Zod schemas
prompt-builder.ts assembles a role-tailored prompt with formatted context
kimi-client.ts spawns the Kimi CLI process, sends the prompt via stdin, and collects stream-json output
response-parser.ts parses the stream-json, extracts tool traces (file reads and web searches), and validates the final JSON response
The structured ConsultResult is returned to Claude Code

Module responsibilities:

| Module | Responsibility | |---|---| | server.ts | MCP server lifecycle, tool registration, input validation, mode switching (auto/manual/disabled) | | kimi-client.ts | Process spawning, stdin/stdout I/O, timeout handling (180s), error classification (retryable vs fatal) | | prompt-builder.ts | Role templates (skeptic/architect/debugger/judge), context formatting, JSON output instructions | | response-parser.ts | Stream-json line parsing, tool call/result pairing, JSON extraction from fenced/raw text, Zod validation |

Four Consultation Roles

| Role | When to Use | What It Does | |---|---|---| | skeptic | Before committing to an approach | Actively challenges assumptions, finds flaws, identifies risks you haven't considered | | architect | Design decisions, tech choices | Reviews for scalability, maintainability, separation of concerns, trade-off analysis | | debugger | Bug investigation hitting a wall | Traces code paths, proposes root cause hypotheses, compares actual vs expected behavior | | judge | Choosing between 2+ options | Objectively evaluates each option against criteria with explicit pros/cons/weights |

Prerequisites

Node.js >= 18
Kimi CLI installed and available in PATH (or configure via KIMI_PATH)

Installation

git clone git@github.com:MichaelCecil/kimi-mcp-server.git
cd kimi-mcp-server
npm install
npm run build

Configuration

Environment Variables

| Variable | Default | Description | |---|---|---| | KIMI_BRIDGE_TOOL_ENABLED | 0 | Set to 1 to enable the consult_kimi tool | | KIMI_BRIDGE_AUTO_ENABLED | 0 | Set to 1 to let Claude proactively call Kimi (otherwise manual only) | | KIMI_BRIDGE_DEBUG | 0 | Set to 1 to enable debug logging to stderr | | KIMI_PATH | kimi | Path to the Kimi CLI binary |

Claude Code MCP Setup

Add to your Claude Code MCP config (~/.claude/settings.json or project-level):

{
  "mcpServers": {
    "kimi-bridge": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/kimi-mcp-server/src/server.ts"],
      "env": {
        "KIMI_BRIDGE_TOOL_ENABLED": "1",
        "KIMI_BRIDGE_AUTO_ENABLED": "0"
      }
    }
  }
}

Two operating modes:

Manual mode (AUTO_ENABLED=0): Claude only calls Kimi when you explicitly ask (e.g., "ask Kimi", "get a second opinion")
Auto mode (AUTO_ENABLED=1): Claude proactively consults Kimi for complex design decisions, stuck debugging, and multi-option evaluations

Usage Examples

Ask Kimi to review an architecture decision

"Ask Kimi as an architect to review the current MCP server design"

Claude will call consult_kimi with role architect, providing the current design, requirements, alternatives, and constraints.

Get a skeptic's take before a risky change

"Have Kimi challenge our approach to the database migration"

Claude will call with role skeptic, providing the proposed approach, goals, constraints, and known risks.

Debug a stubborn bug with a second pair of eyes

"I've tried X, Y, Z and the bug persists — ask Kimi to debug it"

Claude will call with role debugger, providing symptoms, repro steps, logs, expected behavior, and tried approaches.

Compare two implementation options

"Ask Kimi to judge between approach A and approach B"

Claude will call with role judge, providing structured options with pros/cons and evaluation criteria.

Response Format

Every consultation returns a structured ConsultResult:

{
  "parse_ok": true,
  "response": "Detailed analysis grounded in code evidence...",
  "key_risks": ["risk 1", "risk 2"],
  "assumptions": ["assumption the analysis depends on"],
  "alternatives": ["approach not yet considered"],
  "evidence": [
    {
      "tool": "ReadFile",
      "tool_call_id": "call_abc",
      "args": { "path": "src/server.ts" },
      "summary": "First 200 chars of file content..."
    }
  ],
  "confidence": "high: analysis covers all relevant code paths",
  "raw_response_preview": "First 500 chars of raw output...",
  "incomplete_trace": false
}

Key fields to check:

parse_ok — whether Kimi's output parsed into the expected JSON schema
evidence — which files Kimi read and which web searches it performed (verify analysis is grounded)
incomplete_trace — if true, some tool calls were missing results (may indicate timeout or error)

Project Structure

kimi-mcp-server/
├── src/
│   ├── server.ts             # MCP server, tool registration, input validation
│   ├── kimi-client.ts        # Kimi CLI spawning, I/O, timeout, error handling
│   ├── prompt-builder.ts     # Role templates and context formatting
│   └── response-parser.ts    # Stream-JSON parsing, tool trace extraction
├── config/
│   ├── readonly-consultant.yaml  # Kimi agent config (read-only + web tools)
│   ├── system-prompt.md          # Kimi system prompt with security rules
│   └── empty-mcp.json            # Empty MCP config for isolated Kimi runs
├── package.json
├── tsconfig.json
├── README.md                 # English documentation
└── README_CN.md              # Chinese documentation

License

MIT

MCP Servers