Unified Hugging Face

Connect Claude Code to the Hugging Face platform for browsing models, datasets, Spaces, papers, and collections through the Model Context Protocol.

When to Use This MCP Server

Connect this server when you need to:

• Search and explore Hugging Face models to find pre-trained models suitable for your ML application without leaving Claude Code
• Access dataset metadata, preview dataset samples, and find training data for machine learning projects during development
• Browse Hugging Face Spaces, papers, and collections to discover tools, research, and community resources relevant to your work

Consider alternatives when:

• You need to download large model weights or datasets, which is better handled by the Hugging Face CLI (huggingface-cli) or Python library
• You need to fine-tune models or run inference, which requires the Transformers library or Inference API rather than the MCP metadata browser

Quick Start

Configuration

Copy
name: unified-huggingface
type: mcp
category: devtools

Example Connection

Copy
claude mcp:connect unified-huggingface

Available Tools

search-models:      Search Hugging Face models by task, library, or keyword with filters
get-model-info:     Retrieve detailed model card, configuration, and usage information
search-datasets:    Find datasets by task, size, language, or keyword across the Hub
get-dataset-info:   Access dataset documentation, preview samples, and schema details
browse-spaces:      Explore Hugging Face Spaces including demos and applications

Core Concepts

Hugging Face MCP Integration Overview

Aspect	Details
Transport	Remote MCP endpoint at https://huggingface.co/mcp with token auth headers
Authentication	Hugging Face user token for accessing private resources and higher rate limits
Content	Models, datasets, Spaces, papers, and curated collections
Search	Full-text search with task, library, language, and license filters
Metadata	Model cards, dataset cards, configuration files, and usage statistics

Hugging Face Hub Architecture

Claude Code IDE
    |
    v
[MCP Client] --HTTPS--> [Hugging Face MCP Endpoint]
                              |
                              v
                     [Hub API Gateway]
                              |
                    +---------+---------+
                    |         |         |
                    v         v         v
              [Models    [Datasets  [Spaces &
               Index]     Index]    Papers]
                    \         |         /
                     [Hugging Face Hub]
                   500K+ Models | 100K+ Datasets

Configuration

Parameter	Type	Default	Description
HF_TOKEN	string	optional	Hugging Face user access token for private resources and rate limits
default_task	string	none	Default ML task filter (text-generation, image-classification, etc.)
default_library	string	none	Default library filter (transformers, diffusers, sentence-transformers)
sort_by	string	downloads	Default sort order for search: downloads, likes, trending, or modified
max_results	integer	20	Maximum number of results to return from search queries

Best Practices

1. Use Task Filters for Focused Search - Set default_task to the ML task you are working on (e.g., text-generation, object-detection). This narrows search results to models and datasets specifically designed for your use case.

2. Check Model Cards Before Integration - Use get-model-info to read the full model card before integrating a model. Model cards document intended use cases, limitations, training data, and ethical considerations that affect suitability.

3. Authenticate for Private Resources - Configure HF_TOKEN to access private models and datasets in your organization. Unauthenticated requests can only browse public resources and have lower rate limits.

4. Sort by Downloads for Proven Models - When evaluating multiple models for the same task, sort by downloads to surface the most widely used options. High download counts generally correlate with better documentation and community support.

5. Preview Dataset Samples Before Downloading - Use get-dataset-info to preview data samples and schema before committing to a dataset. This prevents downloading large datasets that turn out to have unsuitable format or content.

Common Issues

1. Private Model Returns 404 - Your HF_TOKEN may lack access to the model's organization or repository. Verify that your Hugging Face account has been granted access to the private resource.

2. Search Returns Too Many Irrelevant Results - Add task, library, and language filters to narrow results. Broad keyword searches across the entire Hub return thousands of results; specific filters dramatically improve relevance.

3. Rate Limit Exceeded for Unauthenticated Requests - The Hugging Face MCP endpoint has lower rate limits for unauthenticated requests. Add your HF_TOKEN to the Authorization header to increase your quota.