Hugging Face MCP Server

Hugging Face MCP Server とは？

Hugging Face MCP Server は Shreyas Karnik によるコミュニティ製の huggingface mcp server で、Claude などの MCP クライアントに Hugging Face Hub への読み取り専用アクセスを提供します。モデル、データセット、Spaces、論文、コレクションを検索・参照できます。

ローカルで stdio を介して動作する小さな Python サーバーで、公開 Hub API を呼び出します。Hugging Face 公式の MCP サーバーではありません。Hugging Face は独自のホスト型サーバーを https://huggingface.co/mcp で運営しており、後述の比較セクションで紹介します。

Hugging Face MCP Server の使い方

前提条件：

• uv と Python 3.13 以降（プロジェクトの pyproject.toml は >=3.13 を要求）
• https://github.com/shreyaskarnik/huggingface-mcp-server のローカルクローン
• 任意：https://huggingface.co/settings/tokens で取得した Hugging Face アクセストークンを HF_TOKEN に設定

API キーは不要です。README では HF_TOKEN は任意とされており、レート制限の緩和やプライベートリポジトリへのアクセスに使います。

Smithery（Claude Desktop）

README に記載された Claude Desktop 向けのワンステップインストール：

npx -y @smithery/cli install @shreyaskarnik/huggingface-mcp-server --client claude

Claude Desktop

claude_desktop_config.json を編集します：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "huggingface": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/huggingface-mcp-server",
        "run",
        "huggingface"
      ],
      "env": {
        "HF_TOKEN": "your_token_here"
      }
    }
  }
}

README のサンプルは huggingface_mcp_server.py を実行していますが、現在のリポジトリにはその名前のファイルはありません。サーバーのコードは src/huggingface/ にあり、pyproject.toml が huggingface コマンドを定義しています。Smithery の設定が起動するのもこのコマンドです。そのため上の例では huggingface を実行しています。保存後に Claude Desktop を再起動してください。

Claude Code

同じローカルコマンドを stdio で登録します：

claude mcp add huggingface -- uv --directory /absolute/path/to/huggingface-mcp-server run huggingface

Cursor と VS Code

クライアントの MCP 設定ファイルで、Claude Desktop のエントリと同じ command と args を使います。Cursor や VS Code でワンクリック設定できるリモートサーバーを使いたい場合は、公式のホスト型サーバーを使ってください（後述）。

Hugging Face MCP Server の主な機能

• Hugging Face Hub API への読み取り専用アクセス。アップロード、編集、削除は一切できません。
• モデル、データセット、Spaces、論文、コレクションをカバーする 10 個のツール
• リソース用の独自 hf:// URI スキーム：hf://model/{model_id}、hf://dataset/{dataset_id}、hf://space/{space_id}。いずれも JSON で返されます
• 2 つのプロンプトテンプレート：compare-models（カンマ区切りの model_ids を受け取る）と summarize-paper（arxiv_id を受け取り、任意で detail_level に brief または detailed を指定）
• 設定なしで動作し、HF_TOKEN は任意
• ローカルで stdio を介して動作し、MIT ライセンス
• Smithery または uv でインストール可能

Hugging Face MCP Server のツール

ツールは 5 つのグループに分かれます：

• モデル： search-models はクエリ、作者、タグ、件数で絞り込みます。get-model-info は 1 つのモデルの詳細を返します。
• データセット： search-datasets と get-dataset-info がデータセットについて同じことを行います。
• Spaces： search-spaces は Gradio などの SDK タイプで絞り込めます。get-space-info は 1 つの Space の詳細を返します。
• 論文： get-paper-info は arXiv ID で論文を調べ、Hub 上の実装もあわせて返します。get-daily-papers は厳選されたデイリー論文の一覧を返します。
• コレクション： search-collections と get-collection-info で厳選コレクションを閲覧します。

どのツールも推論の実行やコンテンツの生成は行わず、Hub のメタデータのみを返します。

Hugging Face MCP Server のユースケース

• モデルの発見："Search for BERT models on Hugging Face with less than 100 million parameters."
• モデルの選定："Compare the Llama-3-8B and Mistral-7B models from Hugging Face." この場合は compare-models プロンプトを使えます。
• データセットの調査："Find the most popular datasets for text classification on Hugging Face."
• 研究動向のキャッチアップ："What are today's featured AI research papers on Hugging Face?"
• 論文をすばやく読む："Summarize the paper with arXiv ID 2307.09288 using the Hugging Face MCP server."
• デモを探す："Show me the most popular Gradio spaces for image generation." または："Find collections created by TheBloke that include Mixtral models."

Hugging Face MCP Server と代替ツールの比較

• 公式 Hugging Face MCP サーバー（https://huggingface.co/mcp、ソースは huggingface/hf-mcp-server）。Hugging Face が管理するホスト型サーバーです。HTTP で接続するため、ローカルで何も動かす必要はありません。?login によるサインイン、または Authorization: Bearer <YOUR_HF_TOKEN> ヘッダーに対応しています。ツールと Spaces は https://huggingface.co/settings/mcp で選択します。Hub 検索に加えて、MCP 対応の Gradio Spaces を呼び出すこともでき、たとえば画像を生成できます。Claude Desktop/claude.ai、Claude Code、Gemini CLI、VS Code、Cursor 向けの設定手順が公開されています。Claude Code では：

  claude mcp add hf-mcp-server -t http https://huggingface.co/mcp?login
  

  Cursor や VS Code でトークンを使う場合の公式スニペット：

  "huggingface": {
    "url": "https://huggingface.co/mcp",
    "headers": {
      "Authorization": "Bearer <YOUR_HF_TOKEN>"
    }
  }
  

• このコミュニティ版サーバー。 固定された読み取り専用のツールセットを自分のマシンで動かします。Hugging Face へのログインが不要な小さなローカルプロセスが欲しい場合や、hf:// リソースと 2 つのプロンプトテンプレートを使いたい場合に向いています。リポジトリには 2025 年 3 月以降、新しいコミットがありません。

現在 "hugging face mcp" を検索する人の多くが求めているのは公式のホスト型サーバーです。ローカルの読み取り専用 Hub ブラウザが特に必要な場合に、コミュニティ版を選んでください。

Hugging Face MCP Server のトラブルシューティング

• Claude Desktop でサーバーが起動しない： ログ ~/Library/Logs/Claude/mcp-server-huggingface.log（macOS）または %APPDATA%\Claude\logs\mcp-server-huggingface.log（Windows）を確認します。よくある原因は、uv run にリポジトリに存在しない huggingface_mcp_server.py を指定していることです。代わりに huggingface を実行し、--directory が絶対パスになっていることを確認してください。
• Python バージョンのエラー： このプロジェクトは Python 3.13 以降が必要です。uv に対応するインタープリターをインストールさせるか、既存の Python をアップグレードしてください。
• レート制限エラー： README は Hugging Face トークンの追加を勧めています。ただし現在のソースでは、Hub へのリクエストは認証ヘッダーを付けない通常の HTTP クライアントで送信されるため、トークンを設定しても制限が緩和されない可能性があります。認証付きアクセスが必要なら公式サーバーに切り替えてください。
• ツール呼び出しのデバッグ： MCP Inspector でサーバーを起動します：npx @modelcontextprotocol/inspector uv --directory /path/to/huggingface-mcp-server run huggingface。表示された URL を開いてください。
• ツールが何も返さない： インターネット接続を確認したうえで、huggingface.co で同じモデルやデータセットを検索し、存在することを確かめてください。