{
  "markdown": "# gguf-mcp\n\nAn [MCP](https://modelcontextprotocol.io) server that inspects **local model files** — GGUF and safetensors — so Claude and other LLMs can answer questions about the models on your disk:\n\n- *\"What is this .gguf? Architecture, quantization, parameter count?\"*\n- *\"Will this model fit in my 12 GB GPU at 8k context?\"*\n- *\"What tensors are inside, with what shapes?\"*\n- *\"Show me its chat template / RoPE settings / tokenizer config.\"*\n\n**Headers only.** The parser never touches tensor data, so inspecting a 70 GB model takes milliseconds and a few MiB of I/O. No network, no API keys, no telemetry — your files never leave your machine.\n\n## Quick start\n\n**Claude Code**\n\n```bash\nclaude mcp add gguf -- npx -y gguf-mcp\n```\n\n**Claude Desktop** — add to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"gguf\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"gguf-mcp\"]\n    }\n  }\n}\n```\n\nThe same `npx` invocation works in Cursor, Windsurf, and any other MCP client.\n\n## Tools\n\n| Tool | What it does |\n|------|--------------|\n| `inspect_model` | One-call summary: format, architecture, parameters, quantization, context length, file size, tensor count |\n| `list_tensors` | Tensor names, shapes, and storage types — filterable (`attn`, `blk.0`, ...) |\n| `estimate_vram` | Fit check: exact weights size + modeled fp16 KV cache for your chosen context length |\n| `get_metadata` | The GGUF key-value store (or safetensors `__metadata__`), filterable by key |\n\nPaths can be a `.gguf` file, a `.safetensors` file, a `*.safetensors.index.json`, or a model directory (sharded HuggingFace layouts are aggregated across shards). Extension-less GGUF blobs — like the ones in Ollama's `~/.ollama/models/blobs` — are detected by magic bytes.\n\n## Design notes\n\n- **Context-friendly by construction.** A tokenizer vocabulary is 100k+ strings; metadata arrays are returned as `{count, sample}` summaries and long strings (chat templates) are truncated with a marker. The full data stays on disk where it belongs.\n- **Honest estimates.** `estimate_vram` reports exact on-disk weight bytes plus the standard KV-cache formula (2 × layers × context × KV heads × head dim × 2 bytes), and says what it excludes rather than faking precision.\n- **Defensive parsing.** Magic checks, version checks (incl. big-endian detection), truncation detection, and sanity caps on header sizes — malformed files produce specific, actionable errors.\n- **Zero runtime dependencies** beyond the MCP SDK and zod. The GGUF binary reader and safetensors parser are hand-rolled and unit-tested against synthetic files built in the test suite — no fixtures, no downloads.\n\n## Development\n\n```bash\nnpm install\nnpm test                 # offline unit tests (vitest) — synthetic model files\nnpm run build            # tsc → dist/\nnode scripts/smoke.mjs   # end-to-end: generates models, drives the server over stdio\n```\n\nArchitecture: [`src/gguf.ts`](src/gguf.ts) (binary header parser + VRAM math) and [`src/safetensors.ts`](src/safetensors.ts) (JSON header + shard index) are pure logic with no MCP imports; [`src/index.ts`](src/index.ts) is the MCP wiring and path/format detection.\n\n## Out of scope\n\nTensor statistics (would require reading data), PyTorch `.bin` (pickle — unsafe by design), ONNX, and remote HuggingFace queries (HuggingFace has an official MCP server for that).\n\n## License\n\nMIT\n",
  "bytes": 3374,
  "sha": "dd99905e58b678cfea801e08560e5986834af99f718cfcd6a032e27378cee92a",
  "repo_slug": "arose26/gguf-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_arose26_gguf_mcp_fc817227/readme"
}