MCP HuggingFace Fast Download Tool

⚡ High-speed HuggingFace model downloads with concurrent downloading, resume support, and intelligent retry - 3-5x faster than traditional methods. Supports Claude Desktop, Claude Code, Cursor, VS Code, and other clients.

中文版 | 日本語 | Français | Deutsch

📋 Quick Setup

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "huggingfetch": {
      "command": "npx",
      "args": ["-y", "mcp-huggingfetch@latest"],
      "env": {
        "HUGGINGFACE_TOKEN": "your_token_here"
      }
    }
  }
}

Claude Code

Add to .claude/claude_config.json:

{
  "mcpServers": {
    "huggingfetch": {
      "command": "npx",
      "args": ["-y", "mcp-huggingfetch@latest"],
      "env": {
        "HUGGINGFACE_TOKEN": "your_token_here"
      }
    }
  }
}

Cursor / VS Code (Continue Extension)

Add to config.json:

{
  "mcp": [
    {
      "name": "huggingfetch",
      "command": "npx",
      "args": ["-y", "mcp-huggingfetch@latest"],
      "env": {
        "HUGGINGFACE_TOKEN": "your_token_here"
      }
    }
  ]
}

🔑 Get HuggingFace Token

1. Visit HuggingFace Settings

2. Create a new Access Token

3. Copy the token to HUGGINGFACE_TOKEN in the above configuration

🛠 Usage

After configuration, use the following features directly in conversations:

📋 List Files

View and filter repository files:

List JSON files in the 2Noise/ChatTTS repository

🔍 Explore Repository

Understand repository structure:

Explore the directory structure of microsoft/DialoGPT-medium

🔎 Search Files

Find specific files by name:

Search for config files in openai/whisper-large-v3

📥 Download Models

Selectively download required files:

Please download the ChatTTS model to ./models directory

Download microsoft/DialoGPT-medium model, only .bin files

Download openai/whisper-large-v3 model, exclude test files

📝 Available Tools

File Listing (list_huggingface_files)

List and filter repository files with pattern matching and sorting.

Repository Explorer (explore_huggingface_repo)

Explore repository structure and get hierarchical file tree.

File Search (search_huggingface_files)

Search files by name or pattern within repository.

Download Tool Options (download_huggingface_model)

🔧 Environment Variables

❓ FAQ

Q: Token authentication failed, what should I do?
A: Check if HUGGINGFACE_TOKEN is correctly set, ensure the token is valid and has sufficient permissions.

Q: Download speed is slow, what can I do?
A: The tool supports resume downloads and concurrent downloading. Network issues may cause slow speeds, automatic retry will occur.

Q: How to download private models?
A: Ensure your HuggingFace account has access permissions and use a valid token.

Q: What file formats are supported?
A: All file formats on HuggingFace are supported, including .pt, .bin, .safetensors, .json, .txt, etc.

🏗 Development

Prerequisites

• Node.js 18+

• npm or yarn

Installation

git clone https://github.com/freefish1218/mcp-huggingfetch.git
cd mcp-huggingfetch
npm install

Development Commands

npm run dev          # Run with file watching
npm start           # Run the MCP server
npm run test:basic  # Run basic functionality tests
npm test            # Run Jest unit tests
npm run lint        # Check code style
npm run lint:fix    # Auto-fix linting issues

Release Commands

npm run release:patch  # Release patch version (1.0.0 -> 1.0.1)
npm run release:minor  # Release minor version (1.0.0 -> 1.1.0)
npm run release:major  # Release major version (1.0.0 -> 2.0.0)

The release scripts will automatically:

• Run tests and linting

• Update version number

• Create git tag

• Push to GitHub

• Publish to npm

For more details, see Release Guide

Building

npm run build       # Build single binary
npm run build:all   # Build for all platforms (Linux, macOS, Windows)

📄 License

MIT License - see LICENSE file for details.

📖 Links

• GitHub: freefish1218/mcp-huggingfetch

• Issues: Report Issues

• NPM: mcp-huggingfetch

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.