Content
# Tool List
[](https://github.com/maxliven/cn-llm-bridge/actions/workflows/ci.yml)
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://modelcontextprotocol.io/)
> MCP Bridge: Local Qwen Vision + faster-whisper Transcription, and Kimi K2.7 Code Deep Synthesis.
## What is this?
**cn-llm-bridge** is a set of MCP (Model Context Protocol) servers that connect domestic large models to Claude Code.
```mermaid
graph LR
Client[MCP Client / Claude Code] --> CB[cn_llm_bridge]
Client --> KB[kimi_bridge]
CB --> Qwen[Qwen3.7-Plus<br/>Visual Understanding]
CB --> Whisper[faster-whisper<br/>Local Transcription]
CB --> QwenASR[qwen3-asr-flash<br/>Cloud Transcription]
KB --> Kimi[Kimi K2.7 Code<br/>Deep Synthesis]
```
### Modules
| Module | Capability | Local/Remote | Applicable Scenarios |
|------|------|-----------|---------|
| `cn_llm_bridge` | Visual Understanding + Speech Transcription | Mixed (visual remote, transcription local fallback) | Screenshot Analysis, OCR, Audio to Text |
| `kimi_bridge` | Deep Reasoning + Cross-modal Synthesis | Remote API | Long Text Analysis, Multi-source Integration, Code Generation |
> Choose your main inference model - Claude official, DeepSeek, or any OpenAI compatible model. cn-llm-bridge only handles multi-modal extensions, not bound to the main model.
>
> **Model versions updated with vendors**: All model IDs are configured through environment variables. When a new model is released, update one line in `.env` to switch, no code changes needed.
**Core Concept: Claude Code only schedules, not executes.** It handles orchestration - reads requirements, assigns tasks, and reviews results. The actual inference layer is handled by the most suitable model.
## Quick Start
### 1. Installation
```bash
git clone https://github.com/maxliven/cn-llm-bridge.git
cd cn-llm-bridge
pip install -e .
```
### 2. Get API Key
- **Alibaba Bailian** (required - visual + cloud transcription): [bailian.console.aliyun.com](https://bailian.console.aliyun.com/)
- **Kimi** (optional - deep synthesis): [platform.moonshot.cn](https://platform.moonshot.cn/)
### 3. Configure Claude Code
Add the following to `~/.claude/mcp.json`:
```json
{
"mcpServers": {
"cn-llm-bridge": {
"command": "python",
"args": ["-m", "cn_llm_bridge.server"],
"env": {
"QWEN_API_KEY": "sk-your-key-here",
"BAILIAN_BASE_URL": "https://dashscope.aliyuncs.com/compatible-mode/v1"
}
},
"kimi-bridge": {
"command": "python",
"args": ["-m", "kimi_bridge.server"],
"env": {
"KIMI_API_KEY": "sk-your-key-here",
"KIMI_BASE_URL": "https://api.moonshot.cn/v1"
}
}
}
}
```
Restart Claude Code and ask it "What MCP tools can you see?" - it will list `vision_analyze`, `audio_transcribe`, `kimi_chat`, etc.
### 4. Start using
Directly talk to Claude Code:
- "Analyze this screenshot" → automatically calls `vision_analyze`
- "Transcribe this audio" → automatically calls `audio_transcribe`
- "Compare these three design drafts" → first `vision_analyze` each, then `kimi_synthesize` for integration
> 💡 **Switch model versions**: All model IDs support environment variable overrides. Update one line in `.env` to switch - no code changes needed. See `.env.example`.
## Available Tools
| Tool | Purpose | Model |
|------|------|------|
| `vision_analyze` | Image analysis, returns structured JSON | Qwen3.7-Plus |
| `vision_chat` | Multi-round visual dialogue | Qwen3.7-Plus |
| `audio_transcribe` | Audio transcription | qwen3-asr-flash → faster-whisper (fallback) |
| `kimi_chat` | Deep reasoning, long text analysis | Kimi K2.7 Code |
| `kimi_synthesize` | Multi-source integration, cross-modal synthesis | Kimi K2.7 Code |
| `tools_health` / `kimi_health` | Check model status | — |
## Design Principles
### Principle 1: Generator ≠ Evaluator
**The one who writes and reviews cannot be the same person.** A model reviewing its own output has severe confirmation bias - if it takes a wrong path during generation, it will likely take the same path during review and tell you "no issues".
Claude Code only schedules and reviews, while inference is handled by independent models. The thinking paths of two models are independent, and the blind spots of one are illuminated by the other.
### Principle 2: Structured Output >> Free Text
Let sub-models return JSON, and the main model only reads key fields. A `summary: "login button misplaced"` is 15 tokens, while the main model understanding the entire screenshot may require 500 tokens.
`vision_analyze` returns structured JSON (`summary`, `details`, `text_found`, `objects`), and the main model only needs to read fields for decision-making.
### Principle 3: Parameter Differentiation by Scenario
OCR uses high definition, while scene descriptions can use lower resolution. `_infer_detail_level` automatically infers based on prompt content - if your question contains "text", "recognition", or "OCR", it automatically switches to high definition.
### Principle 4: Transparent Layer Format Constraints
Models sometimes return "JSON wrapped in markdown" - direct parsing will cause errors. `_ensure_json` automatically strips and repairs. The biggest cost of format errors is not the error itself, but the time wasted on troubleshooting.
## Engineering Decisions
### Self-assessment of Complexity
`vision_analyze` lets the model self-assess task complexity (simple/medium/complex) and automatically controls the length of the `details` field. This filters out 80% of low-information-density outputs.
### Adaptive max_tokens
| Task Type | max_tokens | Example |
|---------|-----------|------|
| Search/Listing/Formatting | 300–500 | List page buttons |
| Classification/Matching/Checking | 500–800 | Determine if a screenshot has an error |
| Analysis/Summary/Extraction | 800–1200 | Summarize key points of a scanned document |
| Generation/Writing/Translation | 1200–2000 | Write analysis based on data |
### Single Retry
Encountering 5xx errors, retry once after 1.5 seconds - only once. Excessive retries waste requests on the same obstacle.
## Project Structure
```
cn-llm-bridge/
├── README.md
├── LICENSE
├── pyproject.toml
├── .env.example
├── .gitignore
├── cn_llm_bridge/ # cn-llm-bridge MCP server
│ ├── __init__.py
│ └── server.py
├── kimi_bridge/ # kimi-bridge MCP server
│ ├── __init__.py
│ └── server.py
└── docs/
└── ARCHITECTURE.md # Architecture Details
```
## Dependencies
- Python ≥ 3.10
- `mcp` — MCP protocol SDK
- `httpx` — Asynchronous HTTP client
- `faster-whisper` — Local audio transcription (optional, CPU capable)
## FAQs
**Do I need a GPU?** No. faster-whisper uses INT8 quantization, and CPU is sufficient. Visual and deep synthesis use cloud APIs.
**What audio formats are supported?** m4a, mp3, wav, ogg, flac, etc. Cloud transcription is the main path, and local faster-whisper is a fallback.
**What's the difference from using Claude's official multi-modal capabilities?** Claude's official multi-modal capabilities are the best choice if you can use them stably. cn-llm-bridge solves another problem: model diversity + stability and controllability.
## License
MIT © 2026
*AI capabilities are not about being stronger, but about being more "right".*
## Ecosystem
- [cc-skill-router](https://github.com/maxliven/cc-skill-router) — Skill routing system for Claude Code. Register `cn-llm-bridge` tools as skills for automatic routing.
---
🌐 Part of the [maxliven](https://github.com/maxliven) AI tooling ecosystem:
[cc-skill-router](https://github.com/maxliven/cc-skill-router) ·
[cn-llm-bridge](https://github.com/maxliven/cn-llm-bridge)
