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.

Related MCP server: cloud-chat-assistant

Supported Models

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

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.

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:

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.

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):

# 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)

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)

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).

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