# FreeModel MCP

**Stop paying Claude prices for every task. Route coding to DeepSeek, reasoning to Qwen, writing to Gemini — automatically. One API key, 25+ platforms, the right model every time.**

```bash
npx freemodel-mcp
```

FreeModel is a **model router for Claude Code**. It looks at what you're doing — writing code, analyzing data, translating text — and picks the best model for that specific task. Not just the cheapest. Not just the most popular. The one that actually scores highest on the relevant benchmarks.

---

## Why this exists

Every model router does the same thing: "route cheap prompts to cheap models." They classify by complexity (simple → Haiku, complex → Opus) and call it a day.

FreeModel answers a different question: **which model actually performs well on this type of task?**

```
Other routers:                FreeModel:
"How hard is this?"           "What kind of task is this?"
         ↓                              ↓
  simple / medium / hard        coding / reasoning / writing
         ↓                              ↓
  pick cheaper model            pick model that scores highest
  at same complexity            on this task type's benchmarks
```

The difference is data. FreeModel scores every model across six dimensions (Code, Knowledge, Math, Instruction, Safety, Efficiency) using 18 public benchmarks — LiveCodeBench, MMLU-Pro, MATH-500, IFEval, SimpleQA, and more. The scores are public at [model.leyijian.com/classification.html](https://model.leyijian.com/classification.html).

---

## vs. the alternatives

| | mcp-multi-model | claude-code-llm-router | llm-routing | **FreeModel** |
|---|---|---|---|---|
| Routing logic | keyword match in yaml | complexity regression | confidence score | **6-dim benchmark scores** |
| Task types | none | simple/medium/hard | none | **coding, reasoning, writing, chat, creative, multimodal** |
| Model catalog | 12 platforms, manual config | 20 platforms, auto-detect | 20 platforms | **25 platforms, 982 models** |
| Why this model? | "you configured it" | "complexity match" | "confidence score" | **"scores 92 on coding benchmarks"** |
| Tier system | no | no | no | **L1–L5, public rubric** |
| Subscription routing | no | no | no | **yes, auto-prioritizes paid subs** |
| Pricing | static yaml | static | static | **live API prices** |
| Data transparency | N/A | N/A | N/A | **public classification page** |

---

## How it works

### Tier system (L1–L5)

Every model gets a tier based on six-dimension benchmark scores — not marketing copy, not vibes.

| Tier | Label | Threshold | Example |
|------|-------|-----------|---------|
| L1 | Specialist | single-dim excellence | DeepSeek-R1 (Reasoning 95) |
| L2 | Professional | ≥70 composite | Claude Opus 4, GPT-5 |
| L3 | Competent | ≥55 composite | Qwen3-Max, DeepSeek-V4 |
| L4 | Capable | ≥35 composite | GLM-4-Flash, ERNIE-Speed |
| L5 | Basic | <35 composite | Small/fast models |

### Task auto-detection

6 task types detected from the user's prompt before routing:

- **coding** — 写代码、debug、爬虫、API、build、修复
- **reasoning** — 分析、数学、架构、安全审计、规划
- **writing** — 翻译、写作、总结、报告、文档
- **creative** — 头脑风暴、命名、设计、营销
- **chat** — 问答、推荐、对比、讨论 (default)
- **multimodal** — 图片、OCR、视频

Task type → filter to models that score well on relevant benchmarks → pick best price/performance.

### Scoring dimensions

```
Code ────────── LiveCodeBench, SWE-bench, HumanEval
Knowledge ───── MMLU-Pro, GPQA Diamond
Math ────────── MATH-500, AIME 2024
Instruction ─── IFEval, MT-Bench
Safety ──────── SimpleQA, TruthfulQA
Efficiency ──── speed, throughput, cost
```

18 data sources, 6 dimensions, all public.

---

## Quick start

### Option 1: npx (recommended)

Add to `~/.claude/mcp.json`:

```json
{
  "mcpServers": {
    "freemodel": {
      "command": "npx",
      "args": ["-y", "freemodel-mcp"],
      "env": {
        "FREEMODEL_KEY": "sk-your-key"
      }
    }
  }
}
```

Get a key at [model.leyijian.com](https://model.leyijian.com) → Settings → API Keys.

### Option 2: git clone

```bash
git clone https://github.com/yummy342/freemodel-mcp.git
cd freemodel-mcp && npm install
```

```json
{
  "mcpServers": {
    "freemodel": {
      "command": "node",
      "args": ["/path/to/freemodel-mcp/server.js"],
      "env": {
        "FREEMODEL_KEY": "sk-your-key"
      }
    }
  }
}
```

---

## MCP Tools

| Tool | What it does |
|------|-------------|
| `freemodel_key_health` | Subscription status, platform health, recommended model |
| `freemodel_status` | Session summary: active model, healthy count |
| `freemodel_models` | List your available platforms and models |
| `freemodel_recommend` | Describe a task → get 2-3 model picks with reasons |
| `freemodel_run` | Execute on a specific model (platform + model name) |

### With the skill (recommended)

Install the Claude Code skill for full auto-routing:

1. Copy `skill.md` to `~/.claude/skills/freemodel/skill.md`
2. Claude Code auto-loads it on startup
3. Every task is auto-classified → routed to the best model → executed

The skill adds: subscription priority routing, platform health sorting, quota exhaustion prevention, task-type auto-detection, and model fallback chains.

---

## What you need

1. A FreeModel API key ([get one here](https://model.leyijian.com))
2. Add platform keys in the dashboard (DeepSeek, Alibaba, etc.)
3. Node.js ≥ 18

That's it. No API keys in config files — everything lives in your FreeModel account, encrypted.

---

## Privacy

This is a local relay. Prompts go from your machine → FreeModel API → target platform. No telemetry, no analytics. Your platform API keys stay encrypted in your FreeModel account.

---

## The data

All tier scores, benchmark results, and data sources are public:

→ [model.leyijian.com/classification.html](https://model.leyijian.com/classification.html)

---

## License

MIT