gguf-mcp

gguf-mcp

ローカルモデルファイル（GGUF と safetensors）を検査するMCPサーバーです。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	1 回の呼び出しで概要を表示します。形式、アーキテクチャ、パラメーター、量子化、コンテキスト長、ファイルサイズ、テンソル数
list_tensors	テンソル名、形状、ストレージ型を表示します。attn、blk.0 などで絞り込めます
estimate_vram	選択したコンテキスト長に対して、重みの正確なサイズとモデル化された fp16 KV キャッシュを使って適合性を確認します
get_metadata	GGUF のキーと値のストア（または safetensors の __metadata__）を表示します。キーで絞り込めます

パスには .gguf ファイル、.safetensors ファイル、*.safetensors.index.json、またはモデルディレクトリを指定できます（シャード分割された HuggingFace のレイアウトは、すべてのシャードをまとめて処理します）。Ollama の ~/.ollama/models/blobs にあるファイルのように、拡張子のない GGUF ブロブはマジックバイトで検出されます。

設計上の特長

• コンテキストにやさしい設計です。 トークナイザーの語彙は 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 の接続とパス／形式の検出を行います。

対象外

テンソル統計（データの読み取りが必要になるため）、PyTorch の .bin（設計上安全ではない pickle）、ONNX、リモートの HuggingFace への問い合わせ（その用途には HuggingFace 公式の MCP サーバーがあります）。

ライセンス

MIT