Hugging Face MCP Server
Provides read-only access to the Hugging Face Hub APIs, enabling search and retrieval of models, datasets, Spaces, papers, and collections.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Hugging Face MCP Server compare Llama-3-8B and Mistral-7B models"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
🤗 Hugging Face MCP Server 🤗
A Model Context Protocol (MCP) server that provides read-only access to the Hugging Face Hub APIs. This server allows LLMs like Claude to interact with Hugging Face's models, datasets, spaces, papers, and collections.
Components
Resources
The server exposes popular Hugging Face resources:
Custom
hf://URI scheme for accessing resourcesModels with
hf://model/{model_id}URIsDatasets with
hf://dataset/{dataset_id}URIsSpaces with
hf://space/{space_id}URIsAll resources have descriptive names and JSON content type
Prompts
The server provides two prompt templates:
compare-models: Generates a comparison between multiple Hugging Face modelsRequired
model_idsargument (comma-separated model IDs)Retrieves model details and formats them for comparison
summarize-paper: Summarizes a research paper from Hugging FaceRequired
arxiv_idargument for paper identificationOptional
detail_levelargument (brief/detailed) to control summary depthCombines paper metadata with implementation details
Tools
The server implements several tool categories:
Model Tools
search-models: Search models with filters for query, author, tags, and limitget-model-info: Get detailed information about a specific model
Dataset Tools
search-datasets: Search datasets with filtersget-dataset-info: Get detailed information about a specific dataset
Space Tools
search-spaces: Search Spaces with filters including SDK typeget-space-info: Get detailed information about a specific Space
Paper Tools
get-paper-info: Get information about a paper and its implementationsget-daily-papers: Get the list of curated daily papers
Collection Tools
search-collections: Search collections with various filtersget-collection-info: Get detailed information about a specific collection
Related MCP server: HF MCP Server
Configuration
The server does not require configuration, but supports optional Hugging Face authentication:
Set
HF_TOKENenvironment variable with your Hugging Face API token for:Higher API rate limits
Access to private repositories (if authorized)
Improved reliability for high-volume requests
Quickstart
Install
Installing via Smithery
To install huggingface-mcp-server for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install @shreyaskarnik/huggingface-mcp-server --client claudeClaude Desktop
On MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
On Windows: %APPDATA%/Claude/claude_desktop_config.json
"mcpServers": {
"huggingface": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/huggingface-mcp-server",
"run",
"huggingface_mcp_server.py"
],
"env": {
"HF_TOKEN": "your_token_here" // Optional
}
}
}Development
Building and Publishing
To prepare the package for distribution:
Sync dependencies and update lockfile:
uv syncBuild package distributions:
uv buildThis will create source and wheel distributions in the dist/ directory.
Publish to PyPI:
uv publishNote: You'll need to set PyPI credentials via environment variables or command flags:
Token:
--tokenorUV_PUBLISH_TOKENOr username/password:
--username/UV_PUBLISH_USERNAMEand--password/UV_PUBLISH_PASSWORD
Debugging
Since MCP servers run over stdio, debugging can be challenging. For the best debugging experience, we strongly recommend using the MCP Inspector.
You can launch the MCP Inspector via npm with this command:
npx @modelcontextprotocol/inspector uv --directory /path/to/huggingface-mcp-server run huggingface_mcp_server.pyUpon launching, the Inspector will display a URL that you can access in your browser to begin debugging.
Example Prompts for Claude
When using this server with Claude, try these example prompts:
"Search for BERT models on Hugging Face with less than 100 million parameters"
"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"
"Compare the Llama-3-8B and Mistral-7B models from Hugging Face"
"Show me the most popular Gradio spaces for image generation"
"Find collections created by TheBloke that include Mixtral models"
Troubleshooting
If you encounter issues with the server:
Check server logs in Claude Desktop:
macOS:
~/Library/Logs/Claude/mcp-server-huggingface.logWindows:
%APPDATA%\Claude\logs\mcp-server-huggingface.log
For API rate limiting errors, consider adding a Hugging Face API token
Make sure your machine has internet connectivity to reach the Hugging Face API
If a particular tool is failing, try accessing the same data through the Hugging Face website to verify it exists
Available Tools
10 toolsget-collection-infoC
Get detailed information about a specific collection
Inputs: namespace (required), collection_id (required).
get-daily-papersB
Get the list of daily papers curated by Hugging Face
Inputs: no named parameters.
get-dataset-infoC
Get detailed information about a specific dataset
Inputs: dataset_id (required).
get-model-infoB
Get detailed information about a specific model
Inputs: model_id (required).
get-paper-infoC
Get information about a specific paper on Hugging Face
Inputs: arxiv_id (required).
get-space-infoC
Get detailed information about a specific Space
Inputs: space_id (required).
search-collectionsC
Search for collections on Hugging Face Hub
Inputs: item, limit, owner, query.
search-datasetsC
Search for datasets on Hugging Face Hub
Inputs: tags, limit, query, author.
search-modelsC
Search for models on Hugging Face Hub
Inputs: tags, limit, query, author.
search-spacesC
Search for Spaces on Hugging Face Hub
Inputs: sdk, tags, limit, query, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each resource type (models, datasets, spaces, papers, collections) has a clear search/get pair, so boundaries are generally distinct. The only mild overlap is between get-daily-papers (a curated list) and get-paper-info (a specific paper), but the descriptions distinguish them adequately.
All names follow a hyphenated verb-first pattern (search-X, get-X-info), which is predictable and readable. Minor inconsistency: search tools use plural resource nouns (search-models) while get tools use singular (get-model-info), plus get-daily-papers deviates slightly in structure.
Ten tools is well within the ideal 3-15 range and each is scoped to a distinct resource/action. No redundant or filler tools; the set maps cleanly onto the Hub's main entity types.
Strong coverage of the read/lookup lifecycle across models, datasets, spaces, papers, and collections, covering the hub-browsing domain well. Minor gaps: no general paper search (only curated daily papers) and no file/tree listing or author/org tools, but these are workaround-able.
Related MCP Connectors
Search hub knowledge and memories, read saved context, and create or update hub content.
Web knowledge fetching tools for your agent.
GitHub, npm, PyPI, Stack Overflow, arXiv and OpenAlex paper search as agent tools.
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables access to the Hugging Face Hub API to search and retrieve information about machine learning models, datasets, and their metadata. Provides comprehensive tools for exploring the Hugging Face ecosystem including model details, dataset information, and parquet file access.8MIT
- AlicenseNot gradedqualityDmaintenanceProvides direct access to the Hugging Face Hub for searching models and datasets, fetching metadata, and running inference on text, images, and audio.MIT
- AlicenseAqualityCmaintenanceEnables assistants to search, fetch daily curated lists, retrieve metadata, and generate citations for Hugging Face papers.6104 npmMIT
- AlicenseNot gradedqualityCmaintenanceSearch and retrieve models, datasets, and spaces from Hugging Face Hub. Enables browsing trending items and getting detailed info on repos.117 npmMIT