gguf-mcp

Name: gguf-mcp
Author: arose26

本地服务

github.com/arose26AI 与智能体02 周前更新

代码仓库

关于 gguf-mcp

gguf-mcp 是用于检查本地 GGUF 和 safetensors 模型文件的 MCP 服务。它只读取文件头、不读取张量数据，帮助 LLM 用户查看模型信息并估算显存需求，文件无需上传。

主要功能

01检查模型格式与架构
02查看参数量和量化信息
03列出张量名称、形状和类型
04估算权重与 KV 缓存显存
05筛选读取元数据和配置

适用场景

01判断模型能否在指定上下文长度下装入显卡
02查看模型或分片中的张量
03检查聊天模板和分词器设置

MCP 相关

向 MCP 客户端提供模型检查、张量列表、显存估算和元数据工具。它处理本地文件，不会通过网络发送文件。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

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

启动命令npx -y gguf-mcp

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmgguf-mcp0.1.1stdio

工具

收录的工具列表 · 更新于 3 周前

参数	类型	必填	说明
path	string	是	`.gguf` 或 `.safetensors` 文件、`*.safetensors.index.json` 文件或模型目录的路径

详细介绍

gguf-mcp

一个 MCP 服务，用于检查本地模型文件——GGUF 和 safetensors，让 Claude 和其他 LLM 能够回答有关你磁盘上模型的问题：

“这个 .gguf 文件是什么？架构、量化方式、参数量分别是什么？”
“这个模型在 8k 上下文长度下能装进我的 12 GB GPU 吗？”
“里面有哪些张量，各自的形状是什么？”
“显示它的聊天模板 / RoPE 设置 / 分词器配置。”

仅读取头部。 解析器不会触碰张量数据，因此检查一个 70 GB 的模型只需几毫秒和几 MiB 的 I/O。无需网络、API 密钥或遥测——你的文件不会离开本机。

快速开始

Claude Code

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

Claude Desktop — 添加到 claude_desktop_config.json：

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

同一条 npx 调用也适用于 Cursor、Windsurf 和其他 MCP 客户端。

工具

工具	功能
`inspect_model`	一次调用即可获取摘要：格式、架构、参数量、量化方式、上下文长度、文件大小、张量数量
`list_tensors`	张量名称、形状和存储类型——可筛选（`attn`、`blk.0` 等）
`estimate_vram`	显存适配检查：精确权重大小 + 按所选上下文长度估算的 fp16 KV 缓存
`get_metadata`	GGUF 键值存储（或 safetensors `__metadata__`），可按键筛选

路径可以是 .gguf 文件、.safetensors 文件、*.safetensors.index.json，也可以是模型目录（会聚合分片 HuggingFace 布局中的所有分片）。没有扩展名的 GGUF 文件（例如 Ollama 的 ~/.ollama/models/blobs 中的文件）会通过魔数检测。

设计说明

设计上适合上下文。 分词器词汇表包含 100k+ 个字符串；元数据数组会以 {count, sample} 摘要形式返回，较长的字符串（聊天模板）会截断并附带标记。完整数据会保留在磁盘上，不会被带走。
如实估算。 estimate_vram 会报告精确的磁盘权重字节数，以及标准 KV 缓存公式（2 × 层数 × 上下文长度 × KV 头数 × 头部维度 × 2 字节），并说明未包含的部分，而不会伪造精确度。
防御式解析。 包含魔数检查、版本检查（含大端序检测）、截断检测，以及对头部大小的合理上限检查——格式错误的文件会产生具体且可操作的错误信息。
除 MCP SDK 和 zod 外，运行时零依赖。 GGUF 二进制读取器和 safetensors 解析器均为手写实现，并使用测试套件中构造的合成文件进行了单元测试——无需测试样例文件，也无需下载。

开发

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

架构：src/gguf.ts（二进制头部解析器 + VRAM 计算）和 src/safetensors.ts（JSON 头部 + 分片索引）是纯逻辑，不导入 MCP；src/index.ts 负责 MCP 接线以及路径 / 格式检测。