Provides tools for searching and exploring Hugging Face models, retrieving model details, comparing models, finding similar models, and estimating GPU VRAM requirements across precisions to determine hardware fit.
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., "@hf-model-explorer-mcp Find a 7B instruct model that fits in 12GB VRAM"
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.
An MCP server that lets AI agents search, compare, and right-size Hugging Face models — including estimating whether a model will actually fit in your available GPU VRAM before you download 15GB of weights and find out the hard way.
Works with any MCP-compatible client: Claude, Google Antigravity, Cursor, and others.
Picking a model off Hugging Face usually means checking the model card, guessing at parameter count, mentally doing GB-per-precision math, and hoping it fits your GPU. This wraps that into tools an agent can call directly, so you can ask things like:
"Find me a small instruction-tuned model I can run locally on a 12GB GPU"
and get an actual, sized answer instead of a guess.
Related MCP server: Hugging Face Hub MCP Server
Tool | What it does |
| Search HF Hub by query and task, sorted by downloads/likes/recency |
| Full details on one model: params, license, tags, task |
| Side-by-side comparison of 2–4 models |
| Estimates VRAM needed at fp32/fp16/int8/int4 and whether it fits your GPU |
| Finds lighter/heavier/similar-sized alternatives for the same task |
pip install hf-model-explorer-mcpOr run directly without installing, via uvx:
uvx hf-model-explorer-mcpAdd to your MCP config (claude_desktop_config.json or .mcp.json):
{
"mcpServers": {
"hf-model-explorer": {
"command": "uvx",
"args": ["hf-model-explorer-mcp"]
}
}
}Add to ~/.gemini/antigravity/mcp_config.json (path may vary by Antigravity version —
check Settings → MCP Servers in the IDE):
{
"mcpServers": {
"hf-model-explorer": {
"command": "uvx",
"args": ["hf-model-explorer-mcp"]
}
}
}User: I want to run an instruction-tuned 7B-ish model locally. I have a 12GB GPU.
Agent calls: search_models(query="instruct", task="text-generation")
Agent calls: check_hardware_fit(model_id="mistralai/Mistral-7B-Instruct-v0.2", available_vram_gb=12)
→ {
"parameters": "7.0B",
"recommended_precision": "fp16",
"estimated_vram_by_precision_gb": { "fp16": 15.65, "int8": 7.82, "int4": 3.91 },
"fits": true
}Parameter count comes from the model's safetensors metadata on the Hub. Memory is
estimated as params × bytes_per_param × 1.2 (a 20% overhead margin for activations
and KV-cache), using standard bytes-per-parameter figures:
Precision | Bytes/param |
fp32 | 4.0 |
fp16 / bf16 | 2.0 |
int8 | 1.0 |
int4 | 0.5 |
This is an estimate, not a guarantee — actual usage varies by framework, batch size, and context length. Models without safetensors metadata return an explicit "unknown" rather than a guessed number.
git clone https://github.com/YOUR_USERNAME/hf-model-explorer-mcp
cd hf-model-explorer-mcp
pip install -e ".[dev]"
pytestAll 23 tests mock the Hugging Face API, so the suite runs offline with no rate limits.
PyPI: python -m build && twine upload dist/*
MCP Registry: update server.json with your GitHub username and package version,
then follow the MCP Registry publishing guide
to submit it — typically via mcp-publisher authenticated against your GitHub repo.
MIT
Estimate whether a Hugging Face model will fit in a given amount of GPU VRAM, and at which precision. Uses the model's parameter count and standard bytes-per-parameter figures for each precision, plus a runtime overhead margin for activations and KV-cache. This is an estimate, not a guarantee — actual usage varies by framework, batch size, and context length.
Args: model_id: the HF model repo id, e.g. "mistralai/Mistral-7B-v0.1" available_vram_gb: available GPU VRAM in gigabytes, e.g. 24 precision: specific precision to check, or "auto" to find the lowest-precision option that fits
| Name | Required | Description | Default |
|---|---|---|---|
| model_id | Yes | ||
| precision | No | auto | |
| available_vram_gb | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden of behavioral disclosure. It does disclose that this is an estimate, not a guarantee, and explains the calculation basis (parameter count, bytes-per-parameter, runtime overhead). It does not mention what happens on error (e.g., unknown model ID), network dependencies, or whether it performs any network calls. Given the non-destructive, read-only nature implied by 'estimate,' the description is adequate but could be richer.
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 front-loaded with the core purpose and then provides an Args section with per-parameter explanations. It is concise, with no fluff, and each sentence earns its place. The only minor redundancy is repeating the purpose in the Args section (the 'auto' description), but overall it's well-structured and appropriately sized.
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 tool has three parameters, an output schema, and a moderately complex estimation logic. The description covers the estimation approach, the parameters, and the caveats. It does not mention what happens with invalid input or whether it requires network access, but given the presence of an output schema (which defines return values) and the clear parameter semantics, the description is complete enough for an agent to call the tool correctly. The missing details are edge-case behaviors, not core usage.
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 description coverage is 0%, but the description compensates by providing detailed semantics for each parameter: model_id with a concrete example, available_vram_gb with unit and example, and precision with a clear explanation of each option including the meaning of 'auto'. This goes beyond the schema's titles and enums, giving an agent precise guidance on what values to supply and what they do.
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 tool estimates whether a model fits in a given VRAM amount and at which precision. It uses a specific verb (estimate/check) and resource (hardware fit) and distinguishes it from sibling tools like search_models or compare_models by focusing on VRAM feasibility. The purpose is unambiguous and actionable.
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 explicitly frames the tool as an estimator and cautions that actual usage varies by framework, batch size, and context length. It does not name alternatives or state when to avoid this tool, but the context is clear enough for an agent to infer when it's appropriate: when reasoning about hardware constraints. A slight gap is the lack of explicit 'use this vs. that' routing, but the distinctive purpose covers most of it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compare 2-4 Hugging Face models side by side: parameters, license, downloads, task, and last update.
Args: model_ids: list of 2-4 HF model repo ids to compare
| Name | Required | Description | Default |
|---|---|---|---|
| model_ids | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states what the tool compares but does not mention whether it is a read-only operation, any rate limits, network requirements, or error behavior. It adds minimal context beyond the explicit purpose, which is adequate for a simple comparison but lacks richer behavioral details that an agent might need.
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 two sentences plus an argument list, with no wasted words. The primary purpose is front-loaded, and the argument detail is efficient and necessary given the schema has no descriptions. Every sentence 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?
For a simple tool with one parameter and an output schema, the description is largely complete. It states the input constraints (2-4 models) and the comparison dimensions. The output schema covers return values, so no further detail is needed. It could mention error cases or prerequisite conditions, but these are minor given the simplicity and available structured data.
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 schema description coverage is 0%, so the description must compensate for the undocumented parameter. It does this by specifying that 'model_ids' is a list of 2-4 HF model repo IDs, adding the count constraint and the format ('HF model repo ids') beyond the schema's bare 'array of strings'. This gives the agent actionable semantic meaning for the 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?
The description uses a specific verb ('Compare'), names the resource ('Hugging Face models'), and specifies the exact scope ('side by side') along with the attributes compared (parameters, license, downloads, task, and last update). This clearly distinguishes it from siblings like get_model_details (single model details) and search_models (finding models).
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 usage is implied: the description indicates the tool is for comparing 2-4 models side by side, which suggests when to use it. However, it does not explicitly mention when not to use it, nor does it reference alternative tools (e.g., 'for single model details, use get_model_details'). The guidance is clear but not explicit about alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find alternative models for the same task as the given model, filtered by relative size (lighter, heavier, or similar-sized alternatives).
Args: model_id: the HF model repo id to find alternatives for variant: "lighter" (fewer params), "heavier" (more params), or "same_size" (roughly comparable) limit: max number of alternatives to return (1-20)
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| variant | No | lighter | |
| model_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosing behavioral traits. It explains the core behavior (finding and filtering alternatives) but does not mention any potential side effects, auth requirements, or rate limits, nor does it note that it is a read-only operation. This is adequate for a simple retrieval tool but lacks extra contextual disclosure.
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 efficient: a one-sentence purpose statement followed by an Args list. Every word contributes, and the most important info (purpose) is front-loaded. There is no repetition of schema fields that are self-explanatory for types alone.
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 only 3 parameters, a clear purpose, and the existence of an output schema that likely documents return structure, the description fully covers what an agent needs to call the tool correctly. It explains each parameter and the filtering logic, leaving no gaps beyond what the output schema would cover.
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 description coverage is 0%, so the description must fully compensate. It does: each parameter gets a concise but meaningful explanation—model_id as the HF repo id, variant with the three enum values and what they mean, and limit with the allowed range (1-20). This adds substantial value over the raw schema.
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 opens with a specific verb ('Find') and a precise scope: alternative models for the same task as the given model, filtered by relative size. It clearly distinguishes this from sibling tools like search_models (general search) and compare_models (comparison) by emphasizing same-task and size filtering.
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 it (when you need alternatives for a specific model, filtered by size) through its purpose statement, but it does not explicitly mention sibling alternatives or when-not conditions. It gives clear context without exclusions, so a score of 4 is warranted.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full details for a single Hugging Face model, including parameter count, license, tags, and pipeline task.
Args: model_id: the HF model repo id, e.g. "meta-llama/Llama-3.1-8B-Instruct"
| Name | Required | Description | Default |
|---|---|---|---|
| model_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden; it clearly signals a read-only fetch by using 'Get' and specifies the meaningful output dimensions beyond the output schema. It does not mention error cases or special requirements, but for a simple single-model retrieval there are no major side effects to disclose.
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 main behavior is stated in the first sentence with no filler, followed by a single clearly formatted argument explanation. Every sentence serves a purpose.
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 one-parameter get-details tool, the description covers the required argument, gives an example, and an output schema exists to define the return structure. Nothing critical is missing for successful 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?
Input schema coverage is 0%, and the description fully compensates by explaining that model_id is the Hugging Face model repo id and providing a concrete example ('meta-llama/Llama-3.1-8B-Instruct'). This is exactly what an agent needs to construct a valid call.
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 opens with a specific action and resource: 'Get full details for a single Hugging Face model,' and enumerates the exact content returned (parameter count, license, tags, pipeline task). This clearly distinguishes it from siblings like search_models or compare_models, which serve different purposes.
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 phrase 'for a single Hugging Face model' and the detail list give clear context for when this tool is appropriate, and it stands apart from the search/compare/hardware siblings. It does not explicitly name alternatives or state when not to use it, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Hugging Face Hub for models matching a query, optionally filtered by task (pipeline_tag), sorted by popularity or recency.
Args: query: free-text search, e.g. "llama instruct" or "sentiment analysis" task: optional HF pipeline tag filter, e.g. "text-generation", "text-classification", "image-classification", "translation" limit: max number of results (1-50) sort_by: "downloads" (default), "likes", or "last_modified"
| Name | Required | Description | Default |
|---|---|---|---|
| task | No | ||
| limit | No | ||
| query | Yes | ||
| sort_by | No | downloads |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the search is free-text, that task maps to HF pipeline tags, that sort_by controls ordering, and that limit is capped at 50. These details go beyond the schema alone escal and give an agent confidence about how the tool behaves.
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 clear summary sentence is followed by a compact, alphabetically organized argument block. No filler or repetition; every line adds information that does not appear in the schema.
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 read-only search tool with an output schema presentholer, the description covers all inputs, including default sort and task examples. It lacks nothing essential for making a correct call. The presence of sibling tools in context strengthens understanding, though not explicitly referenced in the description.
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 description coverage is 0%, so the description compensates fully. Each parameter is explained with available values and concrete examples, including the hidden limit constraint (1-50) and the meaning of the enum values. This is exactly the added value needed.
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 opening sentence states a specific verb+resource combination: 'Search Hugging Face Hub for models matching a query'. It also lists optional filters (task, sort), which immediately distinguishes it from sibling tools like get_model_details or compare_models that operate on specific models rather than discovery.
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 clear usage context: it is for free-text discovery of Hugging Face models with optional filtering and sorting. It doesn't explicitly name sibling tools or exclusion conditions, but the task-oriented examples (e.g., 'llama instruct' or 'sentiment analysis') make the intended use obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.1check_hardware_fitcompare_modelsfind_similar_modelsget_model_detailssearch_modelsScored across 5 tools
Each tool has a clearly distinct purpose: search, get details, compare, hardware fit, and find similar models. There is no meaningful overlap between them, even though several take model_id as input.
All tool names follow the same verb_noun snake_case pattern: get_model_details, search_models, compare_models, check_hardware_fit, find_similar_models. The naming is predictable and readable.
Five tools is a well-scoped set for a model exploration server. Each tool adds a distinct capability without redundancy or bloat.
The server covers the full exploration workflow: discovering models via search, inspecting individual models, comparing models, checking hardware compatibility, and finding alternatives. No obvious gaps exist for its stated purpose.
Verified open AI artifact search, trust evidence, downloads, and agent workflows from Hugging Bay.
Will this LLM fit on your GPU, multi-GPU rig or Mac? Exact VRAM & KV-cache math. Read-only.
Which open models fit your GPU or Mac, measured. Model momentum, GPU rental prices, weekly pick.
Which open models fit your GPU or Mac, measured. Model momentum, GPU rental prices, weekly pick.