Hugging Face MCP Server

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

Tool coverage

Hub management

• list_models
• get_model_info
• list_repo_files
• download_file
• whoami
• create_repo
• upload_files
• delete_files
• delete_repo

Local inference

• generate_text
• classify_text
• embed_text
• transcribe_audio
• generate_speech
• 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 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.

Path env values (HF_MODEL_CACHE_DIR, HF_LOCAL_MODEL_PATH, HF_UPLOAD_ROOT) support a leading ~ / ~/. The server expands it with os.homedir() — MCP clients do not shell-expand tilde, so this is required for presets like ~/.cache/huggingface/hub on Windows.

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": "~/.cache/huggingface/hub",
        "HF_LOCAL_MODEL_PATH": "~/.cache/huggingface",
        "HF_ALLOW_REMOTE_MODELS": "true"
      }
    }
  }
}

Mock mode

MOCK=true npx @fre4x/huggingface

Notes

• Local inference uses @huggingface/transformers.
• Hub operations use @huggingface/hub.
• 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.
• transcribe_audio always writes huggingface_transcription_{number}.txt into the current working directory unless output_dir overrides the destination.