FreeLLM-MCP
OfficialThis server exposes live free-LLM performance and availability metrics to AI agents through MCP tools.
List all tracked free models with status, throughput, uptime, and tool-calling support.
Get the currently fastest healthy free model by measured tokens/second.
Get the free model with the highest 7-day uptime among currently answering models.
Get detailed live metrics and error history for a specific model ID.
Run via stdio or Streamable HTTP, with configurable remote/status/cache paths.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@FreeLLM-MCPwhich free model is fastest right now?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
FreeLLM-MCP
An open Model Context Protocol (MCP) server for real-time free LLM performance and availability.
What it does
freellm-mcp exposes live measured metrics from Free LLM Watch (throughput in tokens/sec, availability, 7-day uptime, tool-calling success, and verbatim failure text) to AI coding assistants and agent workflows via the Model Context Protocol.
Agents can use tools like:
list_free_models— list all tracked free models with status and throughput.get_fastest_free_model— find the currently fastest healthy free model.check_model_status— get detailed diagnostics for a specific model ID.get_most_reliable_free_model— find the healthy free model with the best 7-day uptime.
Related MCP server: AgentLayer MCP Server
Install
From a checkout, install the console entry point:
python3 -m pip install .The installed command is freellm-mcp. It has no third-party runtime dependencies; the optional
MCP SDK is only needed for the conformance check.
Usage in Claude Desktop / Cursor
Add to your MCP configuration (claude_desktop_config.json). Use the installed command after
installation, or point directly at server.py in a checkout:
{
"mcpServers": {
"freellm": {
"command": "freellm-mcp",
"args": []
}
}
}By default the server fetches the public board at https://freellmwatch.xyz/api/status.json and
caches it for five minutes. Override the source with FREEMCP_REMOTE_URL, point it at a local status
JSON file with FREEMCP_STATUS_PATH, or move the cache with FREEMCP_CACHE_PATH.
Set FREEMCP_TRANSPORT=http to serve Streamable HTTP on http://127.0.0.1:8901/mcp instead of stdio
(port via FREEMCP_HTTP_PORT).
Local Testing
You can quickly test the server locally with Python:
python3 server.pyAnd feed JSON-RPC initialization requests to stdin.
Run the unit tests and the independent official-SDK conformance check with:
python3 -m pytest -q test_server.py
python3 -m pip install mcp # optional, for the conformance check
python3 conformance_check.pyVerification
test_server.py: 11/11 unit tests pass, including end-to-end HTTP transport checks.conformance_check.py: 14/14 checks pass when run with the optional official MCP SDK.A clean isolated installation resolves as
freellm-watch-mcp 1.1.0; the installedfreellm-mcpentry point completes a negotiated JSON-RPC initialization handshake.Runtime dependencies: none.
Repository Structure
freellm-mcp/
├── server.py # MCP server implementation
├── test_server.py # unit tests
├── conformance_check.py # official SDK conformance check
├── README.md # this documentation
├── pyproject.toml # package metadata and entry point
├── registry.json # example agent configuration
├── .gitignore # generated paths
└── LICENSE # MIT licenseAvailable Tools
4 toolscheck_model_statusA
Get detailed live metrics and error history for a specific free model ID.
| Name | Required | Description | Default |
|---|---|---|---|
| model_id | Yes | The model ID (e.g. gemini/gemini-2.5-flash) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the burden. 'Get' implies a read-only, non-destructive operation, and 'live metrics and error history' indicates the nature of the returned data. Still, it does not disclose error behavior, authorization requirements, rate limits, or how stale the metrics might be – meaningful gaps for an unannotated tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word contributes meaning: 'detailed live metrics and error history' defines the output, and 'specific free model ID' scopes the input.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one required parameter and no output schema, the description provides adequate information: it names the input and the high-level output. Minor gaps remain, such as the exact metrics returned or how errors are surfaced, but nothing essential to selecting and invoking the tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description correctly aligns with the single parameter by mentioning 'a specific free model ID.' The description adds no new syntax, format, or constraints beyond what the schema already provides, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('detailed live metrics and error history') scoped to a specific free model ID. It clearly distinguishes this tool from siblings like list_free_models or get_fastest_free_model, which focus on listing or selecting models rather than inspecting a single model's status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the phrase 'for a specific free model ID' – an agent would use this when it already has a model ID and needs status details. However, there is no explicit guidance on when this tool should be preferred over siblings, no exclusions, and no mention that list_free_models could provide IDs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_fastest_free_modelA
Get the currently fastest healthy free LLM API by measured tokens/second.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states that the tool returns the fastest model measured by tokens/second, implying a health check and comparison, but does not disclose the return format (e.g., model ID vs. object), potential staleness, or edge-case behavior like no available model. It does not contradict any annotations (none exist), but it lacks depth expected for a tool without annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the action and key qualifier ('fastest') and includes the measurement basis. Every word is informative with no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is clear about the tool's function but leaves important context unresolved: the return value's structure is ambiguous (single model name? object? list?) because there is no output schema. It also does not specify whether the measurement is live or cached, which could affect interpretation. For a zero-parameter tool, this is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema is trivially complete. The description correctly omits any parameter details since none exist. No additional semantic explanation is needed, earning the baseline score of 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific verb 'Get', the resource 'fastest healthy free LLM API', and the criterion 'measured tokens/second'. It distinguishes from siblings like get_most_reliable_free_model (reliability) and list_free_models (listing) without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when speed is the priority via the phrase 'fastest healthy free LLM API', but it does not explicitly contrast with alternatives or provide exclusions. There is no mention of when to use get_most_reliable_free_model or check_model_status instead, leaving routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_most_reliable_free_modelA
Get the free LLM API with the highest measured 7-day uptime among those currently answering.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden. It reveals the selection logic ('highest measured 7-day uptime' and 'currently answering'), but it does not disclose the return format, behavior when no models are available, or whether the uptime measurement involves live checks or cached data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the verb and the key criterion. Every phrase earns its place; there is no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-output-schema getter, the description covers the essential semantics: what is returned and how it is selected. It does not specify the exact response shape or failure behavior, but those are minor gaps for a simple lookup tool and no annotations exist to complicate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is no parameter meaning for the description to add; baseline 4 applies. The description's reference to 'currently answering' contextualizes the implicit dynamic input state rather than any schema parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Get'), a specific resource ('free LLM API'), and the precise selection criterion ('highest measured 7-day uptime among those currently answering'). This clearly distinguishes it from the sibling get_fastest_free_model, which optimizes speed rather than reliability.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool—when you need the most reliable currently available free model—but it never names an alternative or states when to prefer another sibling. There is no explicit exclusion or when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_free_modelsA
List all tracked free LLM APIs with live measured status, throughput (tokens/sec), uptime, and tool-calling support.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It does add value by disclosing that the data is 'live measured' and lists the specific metrics returned, giving agents a sense of what to expect. However, it does not mention whether results are sorted, cached, or if there are any rate limits or access considerations—though for a pure list operation these gaps are relatively minor.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-constructed sentence that front-loads the core action ('List all tracked free LLM APIs') and then packs the relevant return fields into a compact list. There is no filler or repetition—every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (no params, no output schema), the description covers what an agent needs to know: the scope of results and the attributes included. It could be slightly more complete by explaining how the list is ordered or how the 'status' is measured, but the absence of parameters and presence of field-list details make it largely sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema is trivially 100% covered. The description does not reference any parameters, which is appropriate since there are none. Baseline for 0 params is 4, and the description does not need to add anything further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and a clearly defined resource ('all tracked free LLM APIs'), and enumerates the exact fields returned (status, throughput, uptime, tool-calling support). This distinguishes it from siblings like get_fastest_free_model and check_model_status, which target a single model or property.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when an agent needs a full overview of all free models), but it does not explicitly reference alternatives or state when NOT to use it. No guidance is given like 'use get_fastest_free_model when you only need the fastest one,' so the usage context is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
4 tool updates
v1.1.0- First observed
check_model_status - First observed
get_fastest_free_model - First observed
get_most_reliable_free_model - First observed
list_free_models
TDQS
Scored across 4 tools
Each tool has a clearly distinct purpose: listing all models, fetching the fastest, fetching the most reliable, and checking status of a specific model. No overlap in function, so an agent can easily select the right tool.
All tool names follow a consistent verb_noun pattern in snake_case: list_free_models, get_fastest_free_model, get_most_reliable_free_model, check_model_status. The pattern is predictable and uniform.
With exactly 4 tools, the server is well-scoped for a read-only model directory. Each tool serves a distinct query need without redundancy or bloat.
The surface covers listing, filtered retrieval (fastest/reliable), and per-model status. Missing an explicit search-by-name tool, but check_model_status covers that by ID. No lifecycle operations are needed for a read-only directory, so minor gap is acceptable.
Maintenance
Related MCP Connectors
Live status and health checks for AI coding providers: Claude, Cursor, Copilot, Codex and more.
Real-time status for 75+ AI services (OpenAI, Anthropic, Cursor). No auth, CORS-enabled.
Live status, API pricing and rate limits for ChatGPT, Claude, Gemini, Cursor and 42+ AI tools.
Live LLM API price + status radar across 11 providers, with public per-model price HISTORY.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceExposes queryable GPU inference benchmark data (quantization, throughput, VRAM, concurrent users) as tools for LLM clients.MIT
- FlicenseNot gradedqualityBmaintenanceProvides real-time AI infrastructure data including LLM costs, model benchmarks, API deprecations, quality scores, and agent spend tracking. Supports authentication, rate limiting, x402 micropayments, and Stripe billing.-
- AlicenseAqualityDmaintenanceEnables AI agents to query LLM and multimodal model benchmarks, pricing, speed, and track model updates via structured diffs using the Artificial Analysis public API.72MIT
- AlicenseNot gradedqualityCmaintenanceProvides AI agents with honest benchmark rankings (Agentic Memory Index and Agentic Search Index) for AI tools, plus graded checks and telemetry for x402 endpoints.14 npmMIT