MCP tools
All tools are read-only, idempotent and deterministic: no LLM runs server-side for MCP calls, so your agent reasons with its own tokens. Results are JSON. Hardware arguments accept anything described in Hardware strings.
estimate_fit
Will one repo run on one device? Checks the repo and its quantized derivatives (GGUF / MLX / AWQ / FP8) and ranks them.
| Parameter | Type / default | Meaning |
|---|---|---|
repo | string | Hugging Face repo id, base model or a quant repo (e.g. Qwen/Qwen3.6-27B, unsloth/gemma-4-26B-A4B-it-GGUF) |
hardware | string | Device (preset id, N×GPU, free text or custom spec) |
ctx | int · 8192 | Context length to fit, in tokens |
ram_gb | float · preset | Override system RAM / unified memory |
kv_cache_dtype | f16 | q8_0 | q4_0 · f16 | KV cache type |
include_vision | bool · false | Count the vision tower / mmproj |
check_quantized_derivatives | bool · true | Also evaluate quant repos built from this model |
Returns model (architecture facts), best and alternatives. Each candidate is described in Reading results.
compare_hardware
One repo across several devices, best first.
| Parameter | Type / default | Meaning |
|---|---|---|
repo | string | Hugging Face repo id |
hardware | string | Comma-separated devices, up to 8 (e.g. "rtx4090, m4max-128, dgx-spark") |
ctx | int · 8192 | Context length |
Returns results[]: hardware, verdict, chosen repo and variant, decode_tps, max_ctx_fit, launch, confidence.
find_models
“What should I run?” as a natural question. Ranks indexed Hub models by fit, task benchmark percentile (vendor-reported and independent kept apart), quant quality and speed.
| Parameter | Type / default | Meaning |
|---|---|---|
question | string | e.g. "best coding model for an RTX 4090 + 64GB RAM at 32k context", "Japanese chat on a Galaxy S25 Ultra", "serve 8 users on 2x RTX 3090" |
Returns the parsed query, answer_markdown, notes and results[] (repo + best candidate).
search_models
Fast index search, no estimate.
| Parameter | Type / default | Meaning |
|---|---|---|
task | string · chat | chat, coding, vision, ocr, embedding, speech-to-text, tts, image-generation, … |
query | string | Boosts repo ids matching this text (e.g. qwen3, gemma-4) |
max_params_billion | float | Upper size bound |
limit | int · 20 | Rows |
list_hardware
The device catalog.
| Parameter | Type / default | Meaning |
|---|---|---|
filter | string | Words matched against id, name, vendor, segment (e.g. h100, amd datacenter, phone samsung, vps) |
limit | int · 40 | Rows |
ask
Free-form questions about running models (runtimes, KV cache, why something runs out of memory). Prefer the tools above when the question is one of those.
Prompts and resources
will_it_run(repo, hardware, ctx),best_for_my_machine(task, hardware, ctx),size_a_server(repo, users, candidates): ready-made prompts that appear as slash commands in some clients.modelread://hardware: the full device catalog as JSON.
Also on Hugging Face
The same tools are available from the Gradio Space patrickbdevaney/modelread-mcp, which you can add at huggingface.co/settings/mcp. Gradio prefixes tool names there (modelread_mcp_estimate_fit, …).