Mcp Multi Model

mcp-multi-model

Give your AI coding agent superpowers — image gen, video gen, web search, and smart multi-model routing. Works with Claude Code, Codex CLI, Gemini CLI, Grok Build, Cursor and any MCP host.

One MCP server. All the models you need. Zero tab-switching.

npx mcp-multi-model

If you find this useful, please give it a ⭐ — it helps others discover the project!

---

What can it do?

🎨 Generate images and videos — right in the terminal

"Generate a macOS app icon with a glowing indigo orb"

Claude calls Nano Banana 2 / Nano Banana Pro / GPT Image 2, saves the PNG, and opens it. No browser, no Figma, no context switch.

Video too — Veo 3.1 generates short clips from a text prompt.

🧠 Smart routing — the right model for the job

Need reasoning / agentic coding → it routes to OpenAI GPT-6 / GPT-5.6 / o-series (auto-handles max_completion_tokens, skips temperature where unsupported). Tell Claude to research something → it routes to Gemini (Google Search grounding). Ask it to write code cheaply → it routes to DeepSeek (fast, cheap, great at code). Need real-time info in Chinese → it routes to Kimi (web search).

You don't pick the model. The routing does it for you.

⚖️ Compare models side by side

"Ask both DeepSeek and Gemini how to implement a B-tree"

Two answers, one terminal. See which model gives you a better solution.

🌐 Web search built in

Gemini uses Google Search grounding. OpenAI GPT-5.6 / GPT-6 search via the Responses API web_search tool (openai-search / openai-pro-search, source URLs attached). Kimi searches the Chinese web. No separate browser-use MCP needed.

🔧 One-line install

{
  "mcpServers": {
    "multi-model": {
      "command": "npx",
      "args": ["-y", "mcp-multi-model"],
      "env": {
        "DEEPSEEK_API_KEY": "sk-...",
        "GEMINI_API_KEY": "AI..."
      }
    }
  }
}

That's it. No git clone, no build step.

---

Supported Models

12+ providers preconfigured in config.example.yaml. Models without an API key are skipped automatically.

Provider	Adapter	Why use it
OpenAI	openai, openai-responses	GPT-6 Astra / GPT-5.6 reasoning, o-series, GPT Image 2. openai-responses adds Responses API web search with cited sources. Reasoning param handling is automatic (max_completion_tokens, temperature skipped where unsupported).
Gemini	gemini	Long context, Google Search grounding. Image (Nano Banana 2 / 2 Lite / Pro) and video (Veo 3.1) generation built in.
DeepSeek	openai	Code, math, logic — extremely low cost
Kimi (Moonshot)	openai	Kimi K2.6 Chinese web search (tool-calling loop) + Kimi K3 flagship reasoning
Grok (xAI)	openai	Real-time X/Twitter context, reasoning
Perplexity	openai	Sonar models with built-in web search and citations
Anthropic (via OpenRouter)	openai	Claude models routed through OpenRouter
Mistral / Groq / Qwen / GLM / Together	openai	EU AI, ultra-fast inference, Chinese-native, open-source aggregators
Ollama / LM Studio / llama.cpp / vLLM	openai	Local — no API key, no cost, full privacy

Adding a new model is one block in config.yaml — see Configuration.

Why these defaults — measured

The routing.categories table in config.yaml is backed by a small benchmark in eval/: 5 task types × 4 prompts × 6 models, run through the server's own adapters (same timeouts, retries, flags and pricing that delegate uses). Code is scored by hidden tests in a node --permission sandbox, extraction by field-level JSON match, reasoning by exact answer, research and creative by a blind rubric grade. First run 2026-10-21: 120 calls, $0.78 total.

model	code	extraction	reasoning	research	creative	overall	avg $/call	median s	timeouts
DeepSeek V4 Flash (deepseek)	100	97	100	100	65	92	$0.0003	2.5	0/20
Gemini 3.8 Flash (gemini)	75	100	100	95	85	91	$0.0059	11.7	1/20
GPT-5.6 Luna (openai)	85	97	100	100	65	89	$0.0004	5.1	0/20
Kimi K2.6 + web search (kimi)	50	100	100	90	55	79	$0.0064	33.9	3/20
DeepSeek V4 Pro (deepseek-pro)	75	100	100	90	80	89	$0.0012	9.9	1/20
Gemini 3.1 Pro (gemini-pro)	100	100	100	70	70	88	$0.0247	17.2	0/20

Quality in %, n = 4 per cell, a 60 s timeout counts as 0. What it means for the defaults:

• code → deepseek — confirmed. 100% on every hidden test, cheapest and fastest of the six; thinking models (Gemini Flash, DeepSeek Pro, Kimi) blew the 60 s timeout on the spec-heavy parser task.
• research → gemini — kept for Google Search grounding, which v0 did not test. On knowledge-stable comparisons DeepSeek and GPT-5.6 Luna scored 100% at 1/15 of Gemini's cost, so for questions that don't need the live web ask_deepseek is the cheaper call.
• creative → gemini — confirmed. Best blind creative score (4.25/5); DeepSeek Pro was close at 1/5 the cost but 4× slower.
• realtime → kimi — not measured (no live-web tasks in v0). Kimi K2.6 is the slowest entry (34 s median, 3/20 timeouts), which is why nothing else is routed to it.
• Pro tiers are explicit, not default — at this difficulty deepseek-pro matched Flash quality 4× slower, and gemini-pro scored lowest on research by ignoring length limits at 4× Flash cost.
• Reasoning and extraction were at ceiling for all six models, so cost and latency decide: DeepSeek Flash.

Method, caveats (n = 4, single latency samples, one blind grader) and per-task results: eval/README.md. Re-run with node eval/run.js run.

MCP Tools

Tools are dynamically generated from your config. With the default setup:

Tool	What it does
ask_ai	Query any model — unified entry with temperature / top_p control
ask_deepseek	Query DeepSeek directly
ask_gemini	Query Gemini directly
ask_kimi	Query Kimi directly
ask_all	Query all models in parallel, compare results
ask_both	Query any two models in parallel
delegate	Smart routing — offloads a self-contained task to the best-fit model by category
generate_image	Text → image via Gemini Nano Banana (default: Nano Banana 2 Lite)
generate_video	Text → video via Gemini Veo
translate	CN ↔ EN translation
research	Deep research with web search
check_health	Ping all models, report status and latency

Every chat tool also takes effort: "fast" | "deep". fast (the default for the everyday entries) maps to low reasoning effort on each provider (Gemini thinking_level, OpenAI reasoning_effort, Kimi K3 reasoning_effort); deep turns the same knobs up for hard analysis. Flagship entries (gemini-pro, openai-pro, openai-pro-search, kimi_k3) default to deep; ask_all runs everything at fast.

Installation

Option 1: npx (recommended)

Add to your MCP host config. Claude Code reads ~/.mcp.json; snippets for Codex CLI, Gemini CLI, Grok Build, Cursor and Cline are under Works with any MCP host.

{
  "mcpServers": {
    "multi-model": {
      "command": "npx",
      "args": ["-y", "mcp-multi-model"],
      "env": {
        "DEEPSEEK_API_KEY": "sk-...",
        "GEMINI_API_KEY": "AI..."
      }
    }
  }
}

Option 2: Clone and run locally

git clone https://github.com/K1vin1906/mcp-multi-model.git
cd mcp-multi-model
npm install
npm run setup   # Interactive setup wizard — validates your API keys

Then add to your MCP config:

{
  "mcpServers": {
    "multi-model": {
      "command": "node",
      "args": ["/path/to/mcp-multi-model/index.js"]
    }
  }
}

API keys can be set via env in the config above, or in a .env file in the project directory.

Works with any MCP host

The server speaks plain stdio MCP, so every host can run it. Two things differ between hosts: how long they let one tool call run, and whether they read the server's built-in instructions. Some calls here are slow by design (ask_all 10-20 s at the default fast effort but a minute or more at deep, openai-pro-search up to 3 min, generate_video several minutes), so check the timeout column. Checked against official docs in October 2026; items marked (secondary) come from community sources.

Host	Config	Default tool timeout	Reads server instructions
Claude Code	~/.mcp.json	long enough	yes (tested 2026-10-23)
Codex CLI	~/.codex/config.toml	60 s, raise it	no (v0.163, tested 2026-10-23), install the skill
Gemini CLI	~/.gemini/settings.json	600 s	yes (tested 2026-10-23)
Grok Build	~/.grok/config.toml, also reads .mcp.json	6000 s	not documented
Cursor	~/.cursor/mcp.json	not documented	not documented
Cline	MCP Servers panel	60 s, raise it	not documented

Codex CLI — ~/.codex/config.toml

[mcp_servers.multi-model]
command = "npx"
args = ["-y", "mcp-multi-model"]
startup_timeout_sec = 30   # default 10; npx cold start can exceed it
tool_timeout_sec = 300     # default 60; ask_all / openai-pro-search / video need more

Codex CLI 0.163 does not inject the server's instructions into the model's context (tested 2026-10-23), so install the skill below: Codex discovers ~/.codex/skills/multi-model/SKILL.md and reads it before calling the tools.

Gemini CLI — ~/.gemini/settings.json

{
  "mcpServers": {
    "multi-model": { "command": "npx", "args": ["-y", "mcp-multi-model"], "timeout": 600000 }
  }
}

Grok Build

grok mcp add multi-model -- npx -y mcp-multi-model
grok mcp doctor multi-model

Grok Build also picks up ~/.claude.json, .cursor/mcp.json and project .mcp.json automatically.

Cursor uses the same JSON shape as Claude Code in ~/.cursor/mcp.json. Its tool timeout is not documented, so keep calls short and avoid ask_all there. Cline users: open the server card in the MCP Servers panel and set Network Timeout to 5 minutes or more.

API keys work the same everywhere: an env block in the host config, or a .env file next to the server.

Teach your agent how to use it: the multi-model skill

Tools are hands; the skill is the brain. skills/multi-model/SKILL.md is an Agent Skills file that tells the agent when to delegate, which model to pick, what each tier costs, how to fact-check with two web-grounded models, why ask_all is for bias detection rather than evidence, and how to handle slow calls on each host. The server also sends a short version of these rules as MCP instructions at startup, so hosts that read it get the basics with zero setup.

Install the full skill once per host (one file, same content everywhere):

Host	Skill path
Claude Code	~/.claude/skills/multi-model/SKILL.md, or load the repo as a plugin: claude --plugin-dir /path/to/mcp-multi-model
Codex CLI	~/.codex/skills/multi-model/SKILL.md (secondary)
Gemini CLI	~/.gemini/skills/multi-model/SKILL.md (secondary)
Grok Build	~/.grok/skills/multi-model/SKILL.md, and it reads Claude Code skills and plugins directly
Cursor	~/.cursor/skills/multi-model/SKILL.md, partial support (secondary)

# example: Codex CLI
curl -fsSL https://raw.githubusercontent.com/K1vin1906/mcp-multi-model/main/skills/multi-model/SKILL.md \
  --create-dirs -o ~/.codex/skills/multi-model/SKILL.md

Configuration

cp config.example.yaml config.yaml

defaults:
  max_tokens: 4000
  temperature: 0.7
  timeout_ms: 60000        # per-model `timeout_ms` overrides this (web / thinking models ship with 120000)
  max_retries: 2
  thinking_headroom: 4000  # added on top of max_tokens for thinking models, so reasoning tokens never eat the answer
  # cache_ttl_ms: 300000   # Cache identical prompts for 5 min
  # daily_budget_usd: 5.0  # Daily spending limit in USD

models:
  deepseek:
    name: DeepSeek
    adapter: openai
    endpoint: https://api.deepseek.com/chat/completions
    api_key_env: DEEPSEEK_API_KEY
    model: deepseek-chat
    description: "Code, math, logic. Low cost."
    fallback_to: gemini
    pricing:
      input: 0.14    # $/M tokens
      output: 0.28

  gemini:
    name: Gemini
    adapter: gemini
    endpoint: https://generativelanguage.googleapis.com/v1beta
    api_key_env: GEMINI_API_KEY
    model: gemini-2.5-flash-preview-04-17
    description: "Long context, broad knowledge, Google Search."
    features:
      - google_search
    timeout_ms: 120000
    effort:                       # per-level overrides of this model's own fields; callers pass effort="fast" | "deep"
      fast: { thinking_level: low }
      deep: { thinking_level: high }
    default_effort: fast          # OpenAI-style models use { reasoning_effort: low | high }; any other field goes in extra_body
    pricing:
      input: 0.10
      output: 0.40

  # Local models — no API key needed:
  # ollama:
  #   name: Ollama
  #   adapter: openai
  #   endpoint: http://localhost:11434/v1/chat/completions
  #   model: llama3.2

Image Generation

Two endpoint families are routed automatically based on the model ID:

Gemini family (uses GEMINI_API_KEY)

Model ID	Endpoint	Notes
gemini-3.1-flash-lite-image (Nano Banana 2 Lite)	:generateContent	Default, ~$0.034/image, lowest latency
gemini-3.1-flash-image (Nano Banana 2)	:generateContent	~$0.067/image, reference-image editing
gemini-3-pro-image (Nano Banana Pro)	:generateContent	~$0.134/image, up to 4K

Imagen 4 (imagen-4.0-*) was retired by Google (all IDs return 404 as of 2026-09) and removed in 3.9.0.

OpenAI family (uses OPENAI_API_KEY)

Model ID	Endpoint	Notes
gpt-image-2	/v1/images/generations	Best text rendering. Requires OpenAI org verification.

Supports aspect_ratio: 1:1, 3:2, 4:3, 16:9, 9:16. quality and size forwarded to OpenAI image endpoints.

Video Generation

Generate short video clips using Gemini Veo 3.1 (uses GEMINI_API_KEY).

Parameter	Type	Notes
prompt	string	Text description of the desired video
aspect_ratio	16:9 / 9:16 / 1:1
duration	4 / 6 / 8 (seconds)	Must be even — Veo only accepts even durations
save_path	string?	Defaults to /tmp/mcp-media/videos/

Local Models

Any OpenAI-compatible local runner works — Ollama, LM Studio, llama.cpp, vLLM:

models:
  ollama:
    name: Ollama
    adapter: openai
    endpoint: http://localhost:11434/v1/chat/completions
    model: llama3.2

Mix local and cloud models freely — use ask_all to compare Ollama vs DeepSeek vs Gemini in one call.

Built-in Features

• Auto-retry & fallback — Exponential backoff on 429/5xx; delegate / research retry once with the category's fallback_chain when the routed model times out or errors, and say so in the reply
• No silent truncation — a cut-off answer ends with [⚠️ Output truncated ...], an all-reasoning answer comes back as a diagnostic, a stalled stream aborts after the model's timeout instead of returning half a reply
• Reasoning budget headroom — thinking models get thinking_headroom extra output tokens so max_tokens means visible answer
• effort on every chat tool — fast (default) or deep, mapped to each provider's own reasoning knob
• Conversation history — Multi-turn context with conversation_id (30min expiry, up to 10 turns)
• Cost tracking — Per-call token usage and cost estimation
• Response caching — Cache identical prompts with configurable TTL
• Daily budget limit — Set a spending cap; calls are blocked when exceeded
• Streaming — Real-time SSE streaming for chat adapters (openai-responses web search is non-streaming)

Privacy

This is a local relay. No telemetry, no analytics, no data is sent to the author. Everything the server sends or runs:

• Prompts go to the providers you configured. Each call sends the prompt, the optional system prompt and, when you pass a conversation_id, the earlier turns of that conversation to the one provider that serves the model you asked for. With the default config.yaml that is OpenAI, Google (Gemini), DeepSeek and Moonshot (Kimi); ask_all sends the same prompt to every chat model at once. Any endpoint you add yourself (Ollama, OpenRouter, ...) receives the same. API keys are read from your environment or .env and sent only to their own provider.
• One version check at startup. The server sends a single GET to https://registry.npmjs.org/mcp-multi-model/latest so it can tell you when a newer version exists. Nothing is sent but the request itself. Set MCP_MULTI_MODEL_NO_UPDATE_CHECK=1 to turn it off.
• Generated files are opened locally. generate_image and generate_video write the file under /tmp/mcp-media/ and, on macOS, run open on it so it shows up right away. Pass save_path to choose the location and skip the auto-open. No other local commands are run.
• Nothing else. No crash reporting, no usage statistics, no third-party SDKs.

Full policy: k1vin1906.github.io/mcp-multi-model/privacy.html

License

MIT