English Français العربية

io.github.arose26/gguf-mcp

Official registry AI and agents

Inspect local GGUF/safetensors models: quantization, params, VRAM fit — headers only.

Source code Documentation

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

NPM package gguf-mcp
Claude Code 
claude mcp add gguf-mcp -- npx -y gguf-mcp@0.1.1
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "gguf-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "gguf-mcp@0.1.1"
            ]
        }
    }
}

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. gguf-mcp
  2. Quick start
  3. Tools
  4. Design notes
  5. Development
  6. Out of scope
  7. License

gguf-mcp

An MCP server that inspects local model files — GGUF and safetensors — so Claude and other LLMs can answer questions about the models on your disk:

  • "What is this .gguf? Architecture, quantization, parameter count?"
  • "Will this model fit in my 12 GB GPU at 8k context?"
  • "What tensors are inside, with what shapes?"
  • "Show me its chat template / RoPE settings / tokenizer config."

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.

Quick start

Claude Code

claude mcp add gguf -- npx -y gguf-mcp

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "gguf": {
      "command": "npx",
      "args": ["-y", "gguf-mcp"]
    }
  }
}

The same npx invocation works in Cursor, Windsurf, and any other MCP client.

Tools

ToolWhat it does
inspect_modelOne-call summary: format, architecture, parameters, quantization, context length, file size, tensor count
list_tensorsTensor names, shapes, and storage types — filterable (attn, blk.0, ...)
estimate_vramFit check: exact weights size + modeled fp16 KV cache for your chosen context length
get_metadataThe GGUF key-value store (or safetensors __metadata__), filterable by key

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

Design notes

  • 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.
  • 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.
  • Defensive parsing. Magic checks, version checks (incl. big-endian detection), truncation detection, and sanity caps on header sizes — malformed files produce specific, actionable errors.
  • 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.

Development

npm install
npm test                 # offline unit tests (vitest) — synthetic model files
npm run build            # tsc → dist/
node scripts/smoke.mjs   # end-to-end: generates models, drives the server over stdio

Architecture: src/gguf.ts (binary header parser + VRAM math) and src/safetensors.ts (JSON header + shard index) are pure logic with no MCP imports; src/index.ts is the MCP wiring and path/format detection.

Out of scope

Tensor statistics (would require reading data), PyTorch .bin (pickle — unsafe by design), ONNX, and remote HuggingFace queries (HuggingFace has an official MCP server for that).

License

MIT

Frequently asked questions

What is io.github.arose26/gguf-mcp?

Inspect local GGUF/safetensors models: quantization, params, VRAM fit — headers only.

How do I install io.github.arose26/gguf-mcp?

It runs on your machine. In Claude Code: claude mcp add gguf-mcp -- npx -y gguf-mcp@0.1.1. For other clients, paste the JSON configuration from this page into their MCP settings.

Does io.github.arose26/gguf-mcp need an API key?

Its registry entry lists no required key or secret. Some features may still need an account with the service it connects to.

Is io.github.arose26/gguf-mcp open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains io.github.arose26/gguf-mcp?

It is published by arose26. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.