Hugging Face Hub Access Gateway (MCP) 🚀

A Model Context Protocol (MCP) endpoint engineered to provide non-mutating access to the Hugging Face repository APIs. This gateway permits large language models, such as Claude, to interface with HF's extensive catalogue of models, data artifacts, interactive Spaces, academic papers, and curated sets.

Exposed Assets

The server maps common Hugging Face assets:

• Custom URI Protocol: Employs the hf:// scheme for resource location.
• Model Endpoints: hf://model/{model_identifier} for accessing machine learning models.
• Dataset Endpoints: hf://dataset/{dataset_identifier} for data collections.
• Space Endpoints: hf://space/{space_identifier} for interactive demonstrations.
• All exposed items include semantic descriptors and utilize the JSON content type for payload delivery.

Predefined Operations (Prompts)

Two primary instructional templates are offered:

• compare-models: Constructs a comparative analysis across several specified Hugging Face models.
• Mandates the model_ids argument (supplied as a comma-separated string).

• Fetches necessary model metadata and structures it for side-by-side review.

• summarize-paper: Generates an abstract of an academic publication sourced from Hugging Face.

• Requires the arxiv_id argument for unique paper identification.
• Offers an optional detail_level parameter (e.g., 'brief' or 'detailed') to govern summary granularity.
• Merges publication abstracts with relevant software implementation data.

Functional Interfaces (Tools)

The server implements the following categories of interaction methods:

• Model Interactions
• search-models: Performs lookups on models, supporting query parameters, ownership filters, tagging criteria, and result limiting.

• get-model-info: Retrieves comprehensive metadata for a single specified model.

• Dataset Interactions

• search-datasets: Executes filtered searches across the dataset catalog.

• get-dataset-info: Fetches detailed specification for a target dataset.

• Space Interactions

• search-spaces: Finds Spaces based on criteria, including the underlying software framework (SDK).

• get-space-info: Obtains in-depth details for a particular Space.

• Paper Interactions

• get-paper-info: Retrieves publication details and associated code references.

• get-daily-papers: Fetches the curated list of recently highlighted research articles.

• Collection Interactions

• search-collections: Queries the collection index using various filtering parameters.
• get-collection-info: Retrieves the contents and metadata of a specific collection.

Setup Parameters

The service operates without mandatory initial setup, though it accommodates optional authentication credentials for the Hugging Face API:

• Set the HF_TOKEN environment variable to your personal Hugging Face security key to benefit from:
• Increased permissible request frequencies (higher rate limits).
• Access privileges to private repositories (subject to user authorization).
• Enhanced connection stability for heavy utilization.

Deployment Guide

Acquisition

Installation via Smithery

To automatically integrate huggingface-mcp-server into Claude Desktop using Smithery:

bash npx -y @smithery/cli install @shreyaskarnik/huggingface-mcp-server --client claude

Claude Desktop Configuration Paths

For macOS users: ~/Library/Application\ Support/Claude/claude_desktop_config.json For Windows users: %APPDATA%/Claude/claude_desktop_config.json

Advanced/Local Server Linking

"mcpServers": { "huggingface": { "command": "uv", "args": [ "--directory", "/absolute/path/to/huggingface-mcp-server", "run", "huggingface_mcp_server.py" ], "env": { "HF_TOKEN": "your_token_here" // Optional credential } } }

Development Lifecycle

Building and Distribution

To prepare the software package for release channels:

1. Synchronize required dependencies and refresh the dependency lock file:

bash uv sync

1. Compile the distributable packages:

bash uv build

This action populates the dist/ folder with source and wheel formats.

1. Upload artifacts to the PyPI repository:

bash uv publish

Note: PyPI credentials must be provided either via command-line flags or environment variables:

• Security Token: Use --token or UV_PUBLISH_TOKEN
• Or credentials pair: Use --username/UV_PUBLISH_USERNAME and --password/UV_PUBLISH_PASSWORD

Diagnostic Procedures

Debugging MCP servers communicating over standard input/output can be complex. For optimal diagnostics, leveraging the MCP Inspector is highly recommended.

To initiate the Inspector using npm with this invocation:

bash npx @modelcontextprotocol/inspector uv --directory /path/to/huggingface-mcp-server run huggingface_mcp_server.py

Once started, the Inspector will present a web address where you can connect your browser to monitor the session.

Illustrative Prompts for LLM Integration

When integrating this service with Claude, consider these sample queries:

• "Query Hugging Face for models architecturally similar to BERT, possessing fewer than 100 million adjustable parameters."
• "Identify the most utilized datasets available for text classification tasks within the Hugging Face ecosystem."
• "What research articles related to AI have been highlighted in the Hugging Face daily digest today?"
• "Use the Hugging Face MCP endpoint to generate an abstract for the paper identified by arXiv ID 2307.09288."
• "Contrast the performance characteristics of the Llama-3-8B and Mistral-7B architectures hosted by Hugging Face."
• "Display the top-ranked Gradio applications designed for visual generation tasks."
• "Locate data collections authored by TheBloke that explicitly feature Mixtral variants."

Issue Resolution

Should operational problems arise with the server:

1. Review the server output logs within Claude Desktop:
2. macOS path: ~/Library/Logs/Claude/mcp-server-huggingface.log

3. Windows path: %APPDATA%\Claude\logs\mcp-server-huggingface.log

4. If rate limiting is encountered, apply a Hugging Face API key as an environment variable.

5. Verify local system network connectivity to the Hugging Face API endpoints.

6. If a specific tool malfunctions, attempt to manually retrieve the identical data via the official Hugging Face web portal to confirm resource existence.

WIKIPEDIA: XMLHttpRequest (XHR) is an Application Programming Interface, typically realized as a JavaScript object, designed to facilitate the transmission of Hypertext Transfer Protocol (HTTP) requests from a web browser client to a remote web server. These methods empower a browser-based application to dispatch requests to the server subsequent to the initial page load completion, and subsequently process incoming information. XMLHttpRequest forms a fundamental pillar of Asynchronous JavaScript and XML (Ajax) programming methodology. Prior to the adoption of Ajax, the primary means of server interaction involved traditional hyperlink navigation and form submissions, actions that frequently necessitated a full page refresh.

== Background == The underlying concept for XMLHttpRequest was first conceptualized in 2000 by developers associated with Microsoft Outlook. This concept was subsequently materialized within the Internet Explorer 5 browser release (1999). Notably, the initial implementation did not utilize the standardized XMLHttpRequest identifier; instead, developers relied on the ActiveXObject("Msxml2.XMLHTTP") or ActiveXObject("Microsoft.XMLHTTP") instantiations. As of Internet Explorer version 7 (released in 2006), universal support for the official XMLHttpRequest identifier became standard across all major browser platforms. The XMLHttpRequest identifier has since established itself as the prevailing protocol across all leading web browsers, including Mozilla's Gecko rendering engine (2002), Apple's Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Efforts === The World Wide Web Consortium (W3C) formally published a Working Draft specification for the XMLHttpRequest object on April 5, 2006. A subsequent Working Draft specification, designated Level 2, was issued by the W3C on February 25, 2008. Level 2 introduced enhanced functionality such as event progress monitoring, facilitation of cross-origin requests, and mechanisms for handling raw byte streams. By the conclusion of 2011, the enhancements introduced in Level 2 were integrated back into the primary specification document. In late 2012, stewardship for the specification was transferred to the WHATWG, which currently maintains the living document using Web IDL definitions.

== Operational Flow == The typical procedure for executing a request using XMLHttpRequest involves a sequence of programming steps.

First, an XMLHttpRequest object instance must be instantiated by invoking its constructor function: Next, the open() method is called to define the transaction type (e.g., GET, POST), specify the target resource Uniform Resource Identifier, and determine whether the operation will execute synchronously or asynchronously: If an asynchronous mode is chosen, an event handler must be established to receive notifications upon changes in the request's lifecycle status: Initiation of the data transfer is performed by calling the send() method, potentially carrying payload data: Finally, the logic must respond to status changes within the registered event listener. Upon receipt of server response data, this is typically available in the responseText property. When the object completes processing the transaction, its state transitions to 4, signifying the "done" status. Beyond these fundamental steps, XMLHttpRequest offers numerous parameters to fine-tune request transmission and response handling. Custom header fields can be appended to direct server behavior, and data can be transmitted to the server via the argument provided to the send() call. The server response can be programmatically parsed from JSON format into an immediately usable JavaScript structure, or it can be processed incrementally as data chunks arrive, foregoing the necessity to wait for the complete text buffer. Furthermore, the request can be terminated prematurely or configured to automatically fail if a specified time limit is exceeded.

== Inter-domain Communication ==

During the nascent stages of the World Wide Web's evolution, issues arose regarding the feasibility of executing requests that crossed security boundaries (brea