---
name: modelread
description: Check whether a Hugging Face model fits and how fast it runs on specific hardware (GPU, Mac, phone, multi-GPU node, cloud instance), pick the right quant (GGUF/MLX/AWQ/FP8), and get the llama.cpp / vLLM / MLX launch command. Use before downloading, quantizing, serving or benchmarking a local model, when choosing a model for a device, or when sizing a cloud GPU.
---

# modelread

modelread reads a repository's real files and tensor headers and returns a fit verdict, the best quant, decode and
prefill tokens/sec as calibrated ranges, the longest context that fits, the memory placement, and a launch command.

## Setup (once)
If the `modelread` MCP tools are not available, add the server:
`claude mcp add --transport http --scope user modelread https://modelread.com/mcp`
Without MCP, use the HTTP API: `curl "https://modelread.com/api/estimate?repo=<org/repo>&hw=<id>&ctx=<n>"`.

## When to call it
- Before `hf download`, `llama-server -hf`, `vllm serve` or `mlx_lm.server`: confirm the variant fits at the context you need.
- When the user asks which model or quant to run on a device, or "how fast will it be".
- When choosing a cloud instance: compare devices with `compare_hardware`; answers include $ per million output tokens.
- After a real run, compare the measured tok/s to the range; if far outside, say so.

## Hardware strings
Preset ids (`rtx4090`, `m4max-128`, `dgx-spark`, `8x-h100-sxm`, `jetson-thor`, `iphone-17pro-12`), `2x-rtx3090`,
free text ("MacBook Pro M4 Max 64GB", "AWS g6e.xlarge"), or `gpu=24,ram=64,bw=936`. Detect the local machine with
`nvidia-smi --query-gpu=name,memory.total --format=csv` or `system_profiler SPHardwareDataType` when unsure.

## Reading results
- `verdict`: fits / fits-tight / offload (runs, slower) / no. Offload is valid: prefer it to a much smaller model only if speed matters.
- Quote `decode_tps` as a range (lo–hi, typical mid). `calibrated: false` means the range is wider.
- Use `launch` verbatim, then adjust context (-c / --max-model-len) to what the user needs; keep within `max_ctx_fit`.
- Surface `reasons`, `unknowns` and `warnings`. A "modified derivative" or "renamed derivative" reason means the repo
  changed the weights (fine-tune, merge, prune, abliteration): not a faithful quant of the base.
- For serving many users, read `decode_tps.aggregate` (llama-server slots) or `tensor_parallel` (vLLM/SGLang on nodes).
