Hugging Face MCP Server

MCP server for Hugging Face Hub management and local multimodal inference in Node.js.

Tool coverage

Hub management

• huggingface_list_models
• huggingface_get_model_info
• huggingface_list_repo_files
• huggingface_download_file
• huggingface_whoami
• huggingface_create_repo
• huggingface_upload_files
• huggingface_delete_files
• huggingface_delete_repo

Local inference

• huggingface_generate_text
• huggingface_classify_text
• huggingface_embed_text
• huggingface_transcribe_audio
• huggingface_generate_speech
• huggingface_image_to_text

Environment variables

• HF_TOKEN or HUGGINGFACE_ACCESS_TOKEN: Optional for public reads, required for authenticated Hub operations.
• HF_UPLOAD_ROOT or HUGGINGFACE_UPLOAD_ROOT: Optional safe root for huggingface_upload_files. Defaults to the current working directory.
• HF_MODEL_CACHE_DIR: Optional cache directory for local model downloads.
• HF_LOCAL_MODEL_PATH: Optional local model directory for offline-only runs.
• HF_ALLOW_REMOTE_MODELS: Set to false to force local-only model loading by default.
• MOCK: Set to true for offline mock mode.

Claude Desktop configuration

{
  "mcpServers": {
    "huggingface": {
      "command": "npx",
      "args": ["-y", "@fre4x/huggingface"],
      "env": {
        "HF_TOKEN": "hf_your_access_token",
        "HF_UPLOAD_ROOT": "/absolute/path/to/upload-root",
        "HF_MODEL_CACHE_DIR": "/absolute/path/to/.cache/huggingface",
        "HF_LOCAL_MODEL_PATH": "/absolute/path/to/models",
        "HF_ALLOW_REMOTE_MODELS": "true"
      }
    }
  }
}

Mock mode

MOCK=true npx @fre4x/huggingface

Notes

• Local inference uses @huggingface/transformers.
• Hub operations use @huggingface/hub.
• huggingface_upload_files accepts only local files under the configured upload root. Remote HTTP(S) URLs are rejected.
• Local speech-to-text file decoding currently expects local WAV files for filesystem inputs. Remote HTTP(S) audio URLs are passed through directly.