# ai-model-selector-mcp

MCP server that gives AI assistants structured access to model metadata for 76+ AI models across Ollama, Claude, and OpenRouter.

Query capabilities, check compatibility, compare models, and get task-based recommendations — all via the [Model Context Protocol](https://modelcontextprotocol.io/).

---

## Quick start

### Claude Code

Add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "ai-model-selector": {
      "command": "npx",
      "args": ["-y", "ai-model-selector-mcp@latest"]
    }
  }
}
```

Restart Claude Code. The tools are now available.

### Other MCP clients

Any MCP-compatible client can connect via stdio:

```bash
npx ai-model-selector-mcp
```

---

## How it works

```
Claude Code (or any MCP client)
    │
    │  JSON-RPC over stdio
    ▼
ai-model-selector-mcp
    │
    │  imports catalog data
    ▼
ai-model-selector/catalog
    (76+ model entries with capabilities,
     parameter sizes, exclusion rules)
```

The MCP server wraps the [ai-model-selector](https://www.npmjs.com/package/ai-model-selector) catalog — a curated dataset of AI model metadata. No external API calls, no database, no network access. All data is bundled.

---

## Tools

### `get_model_metadata`

Look up a single model's capabilities, parameter size, and exclusion rules.

```
Input:  { modelId: "gemma3:12b" }
Output: { capabilities: ["general", "writing"], description: "Google all-rounder", parameterSize: "12B" }
```

### `filter_models`

Filter the catalog by capability tags and/or mode compatibility.

```
Input:  { capabilities: ["coding"], excludeMode: "json-output" }
Output: { models: [...], count: 5 }
```

### `check_compatibility`

Pre-flight check: is this model compatible with a given mode?

```
Input:  { modelId: "phi4-reasoning", mode: "json-output" }
Output: { compatible: false, reason: "Model excluded from json-output mode...", model: {...} }
```

### `compare_models`

Side-by-side comparison of 2+ models — shared and unique capabilities.

```
Input:  { modelIds: ["gemma3:12b", "claude-sonnet"] }
Output: { comparison: [...], sharedCapabilities: ["general", "writing"], uniqueCapabilities: { "claude-sonnet": ["coding"] } }
```

### `recommend_model`

Task-based model recommendation with scoring.

```
Input:  { task: "coding", mode: "json-output", preferSmall: true }
Output: { recommended: [{ pattern: "codegemma", score: 4, ... }, ...] }
```

Scoring: +3 primary capability match, +1 secondary, -10 if excluded from mode, +1 if small model preferred and <= 7B.

---

## Resources

| URI | Description |
|-----|-------------|
| `models://catalog` | Full 76+ model catalog as JSON |
| `models://capabilities` | Capability types with model counts and badge colors |
| `models://providers` | Provider (Ollama, Claude, OpenRouter) to model family mapping |

---

## Model catalog

The catalog covers 76 model patterns across 3 providers:

| Capability | Models | Examples |
|------------|--------|----------|
| reasoning | 6 | phi4-reasoning, deepseek-r1, qwq |
| coding | 5 | codegemma, starcoder2, codellama |
| writing | 5 | mistral, dolphin3, neural-chat |
| general | 15+ | gemma3, qwen3, llama3.3, phi4 |
| vision | 3 | llava, bakllava, llama3.2 |
| research | 6 | phi4-reasoning, deepseek-r1 |

Models with `excludeFromModes: ["json-output"]` are reasoning models that generate `<think>` tags, which break JSON parsing in structured output workflows.

---

## Development

```bash
git clone https://github.com/barrymister/ai-model-selector-mcp.git
cd ai-model-selector-mcp
npm install
npm run build
```

Test locally:

```bash
# Add to .mcp.json for local testing
{
  "mcpServers": {
    "ai-model-selector": {
      "command": "node",
      "args": ["path/to/ai-model-selector-mcp/dist/index.js"]
    }
  }
}
```

---

## Related projects

- [ai-model-selector](https://www.npmjs.com/package/ai-model-selector) — React components and hooks for AI model selection (the catalog data source)
- [llm-eval-pipeline](https://github.com/barrymister/llm-eval-pipeline) — Multi-provider LLM evaluation with MLflow experiment tracking

---

## License

MIT