Skip to main content
Glama

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.py

And 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.py

Verification

  • 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 installed freellm-mcp entry 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 license

Available Tools

4 tools
check_model_statusA

Get detailed live metrics and error history for a specific free model ID.

ParametersJSON Schema
NameRequiredDescriptionDefault
model_idYesThe model ID (e.g. gemini/gemini-2.5-flash)

TDQS

A3.8/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.9/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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.

  1. 4 tool updatesv1.1.0
    • First observedcheck_model_status
    • First observedget_fastest_free_model
    • First observedget_most_reliable_free_model
    • First observedlist_free_models

TDQS

A4.2/5.0

Scored across 4 tools

Disambiguation5/5

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.

Naming Consistency5/5

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.

Tool Count5/5

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.

Completeness4/5

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

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers