ModelLens
Probe, rank and recommend models behind any OpenAI-compatible gateway
- 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-mcpAdd to claude_desktop_config.json
{
"mcpServers": {
"modellens": {
"command": "uvx",
"args": [
"modellens-mcp"
]
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"modellens": {
"command": "uvx",
"args": [
"modellens-mcp"
]
}
}
}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 JSONMODELLENS_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.



