Skip to content
MCP server

ModelLens

Probe, rank and recommend models behind any OpenAI-compatible gateway

Runs locallyStatus and history
Install
Pricing
Open source
Platforms
CLI, self-hosted, API
Runs
Locally
Version
0.1.3
Listing updated
today

Similar MCP servers

About ModelLens

ModelLens is an open-source MCP server for ai models and llm tooling. It runs locally on your machine and is started by your AI client.

A gateway may advertise 89 models while only a handful answer quickly. ModelLens sends real requests to find out, recording latency, success, cancellation, streaming and tool-calling per model, then keeps up to 200 probes of history per model in a JSON file.

Scores weigh success rate at 50%, median latency at 30% and cancellation rate at 20%. Each model gets a verdict such as healthy, mixed, unreliable, quota_blocked or dead. The README's example run found a routing group that listed an 87-second model first and a 0.9-second one third.

It runs on the Python standard library alone and also works as a command-line tool. Probing spends tokens, and a single probe is weak evidence, so the README advises keeping the limit modest and reading scores after several runs. Only the OpenAI-compatible /v1/models route is supported for now.

Install

Run in a terminal

claude mcp add modellens -- uvx modellens-mcp

Add to claude_desktop_config.json

{
  "mcpServers": {
    "modellens": {
      "command": "uvx",
      "args": [
        "modellens-mcp"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "modellens": {
      "command": "uvx",
      "args": [
        "modellens-mcp"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

Add to .vscode/mcp.json

{
  "servers": {
    "modellens": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "modellens-mcp"
      ]
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "modellens": {
      "command": "uvx",
      "args": [
        "modellens-mcp"
      ]
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "modellens": {
      "command": "uvx",
      "args": [
        "modellens-mcp"
      ]
    }
  }
}

Using several servers? Build one config file with the MCP config generator.

Configuration

  • MODELLENS_CONFIGPath to the endpoint configuration JSON
  • MODELLENS_DATAPath to the probe history JSON

Tools this server provides (5)

Taken from the project documentation; the running server may differ.

list_models
Lists what each endpoint advertises, with an optional substring filter.
probe
Sends real requests to measure latency, success, streaming and tool calls.
ranking
Ranks models from recorded history.
recommend
Recommends a model for a fast, cheap or capable profile.
report
Returns the whole picture as markdown.

What it does

Live model probing
Sends real requests and records latency, success, streaming and tool-call support.
Weighted scoring
Combines success rate, median latency and cancellation rate into one score.
Health verdicts
Labels each model healthy, mixed, unreliable, quota_blocked, dead or untested.
Profile recommendations
Suggests a model for a fast, cheap or capable profile.
Probe history
Keeps the newest 200 probes per model so rankings improve with use.
Markdown report
Produces a full picture of all endpoints as markdown.
No dependencies
Python 3.9+ standard library only, with a matching command-line mode.

Good for

  • Find which models on a gateway actually respond right now
  • Reorder a router group that puts a slow model first
  • Check a new provider by probing it once before adopting it
  • Notice a provider degrading before users complain
  • Pick a model for a fast, cheap or capable profile

Pricing

Open source

MIT; optional hosted endpoint charges $0.01 to $0.05 per call in USDC

ModelLens FAQ

Which gateways does it work with?

Any OpenAI-compatible endpoint, such as OpenAI, a local Ollama server or a self-hosted gateway, listed in a JSON config.

Does probing cost money?

Yes. Each probe is a real completion, so keep the limit sensible.

Is there a hosted version?

Yes. A hosted endpoint charges per call with x402 in USDC on Base: list_models is free, ranking and recommend cost $0.01, report $0.02 and probe $0.05.

What license is it under?

MIT.

Is ModelLens free?

Yes. ModelLens is open source, so you can use and self-host it for free.

How do I add ModelLens to Claude Code?

Run this command in your terminal: claude mcp add modellens -- uvx modellens-mcp

What are the best alternatives to ModelLens?

The closest alternatives to ModelLens are headroom, omniget, next-ai-draw-io, mcp-for-blender and Claude Code Ultimate Guide.

Where this comes from

  • Description: written from the project's README.
  • Install steps: from the official MCP Registry entry.

How AIPoweredBot checks servers