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 Servercompare 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: Hugging Face Hub 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
| Name | Required | Description | Default |
|---|---|---|---|
| namespace | Yes | The namespace of the collection (user or organization) | |
| collection_id | Yes | The collection slug, with or without the namespace prefix |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. 'Get' implies a non-mutating read, but the description says nothing about what 'detailed information' contains, error behavior for a missing/invalid collection, or any permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short, front-loaded sentence with no filler. It is efficient, though it is arguably too terse to convey much.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read tool with full schema coverage, the definition is minimally viable. With no output schema and no annotations, however, it leaves the agent without any sense of what data comes back or how to recover from a bad identifier.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (namespace, collection_id) are already documented in the schema. The description adds no syntax, format, or identifier details beyond that, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Get) plus resource (collection) and scope (a specific one, detailed info). An agent can distinguish it from search-models/get-model-info style siblings by the resource name, but nothing in the text differentiates it from search-collections or explains what 'detailed' covers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance, no prerequisites, and no mention of the sibling search-collections that would be the alternative when the collection identifier is unknown. Usage is only implied by the phrase 'a specific collection'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get-daily-papersB
Get the list of daily papers curated by Hugging Face
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool retrieves a list but doesn't add context like whether it's read-only, requires authentication, has rate limits, or what the return format looks like. This is a significant gap for a tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without any wasted words. It's appropriately sized and front-loaded, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete. It doesn't explain behavioral traits like safety or return values, and while it's concise, it fails to provide enough context for the agent to understand how to use it effectively beyond the basic action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and schema description coverage is 100%, so there are no parameters to document. The description doesn't need to add parameter semantics, and it appropriately doesn't mention any, earning a baseline high score for this dimension.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Get') and resource ('list of daily papers curated by Hugging Face'), making it easy to understand what it does. However, it doesn't differentiate from sibling tools like 'get-paper-info' or 'search-collections', which might also retrieve paper-related information, so it misses full sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention context, exclusions, or compare to siblings such as 'get-paper-info' or 'search-collections', leaving the agent with no usage instructions beyond the basic purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get-dataset-infoC
Get detailed information about a specific dataset
| Name | Required | Description | Default |
|---|---|---|---|
| dataset_id | Yes | The ID of the dataset (e.g., 'squad') |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It states this is a read operation ('Get'), but doesn't mention authentication requirements, rate limits, error conditions, response format, or whether it returns metadata, statistics, or other details. For a tool with zero annotation coverage, this is inadequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's appropriately sized for a simple retrieval tool and front-loads the essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is insufficiently complete. It doesn't explain what 'detailed information' includes, the response format, or behavioral aspects like error handling. For a tool that presumably returns structured data about datasets, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with the single parameter 'dataset_id' fully documented in the schema. The description adds no additional parameter information beyond what's already in the structured schema, so it meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get detailed information') and resource ('about a specific dataset'), making the purpose understandable. However, it doesn't distinguish this tool from potential siblings like 'search-datasets' or 'get-collection-info' that might also provide dataset information, preventing a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With siblings like 'search-datasets' available, there's no indication whether this is for known dataset IDs versus exploratory searches, or how it differs from other info-retrieval tools like 'get-model-info'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get-model-infoB
Get detailed information about a specific model
| Name | Required | Description | Default |
|---|---|---|---|
| model_id | Yes | The ID of the model (e.g., 'google/bert-base-uncased') |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the tool retrieves information, implying a read-only operation, but doesn't disclose behavioral traits such as authentication requirements, rate limits, error handling, or what 'detailed information' entails. This leaves significant gaps for an agent to understand how to use it effectively.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. It's front-loaded with the core purpose, making it easy to scan and understand quickly. Every word earns its place, adhering to best practices for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (1 parameter, no output schema, no annotations), the description is minimally adequate. It states what the tool does but lacks details on behavior, output format, or error cases. Without annotations or output schema, more context would be helpful for completeness, but it's not severely lacking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the single parameter 'model_id' well-documented in the schema. The description adds no additional meaning beyond the schema, such as examples of model IDs beyond the one in the schema or constraints. Baseline 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get detailed information') and resource ('about a specific model'), making the purpose understandable. It distinguishes from siblings like 'search-models' by focusing on retrieving details for a single model rather than searching. However, it doesn't specify what 'detailed information' includes, which keeps it from being fully specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need details for a known model ID, as opposed to 'search-models' for finding models. However, it lacks explicit guidance on when to use this versus alternatives like 'get-collection-info' or 'get-dataset-info', and doesn't mention prerequisites or exclusions, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get-paper-infoC
Get information about a specific paper on Hugging Face
| Name | Required | Description | Default |
|---|---|---|---|
| arxiv_id | Yes | The arXiv ID of the paper (e.g., '1810.04805') |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool 'gets information' but doesn't clarify what kind of information is returned, whether it's read-only, if there are rate limits, authentication requirements, or error conditions. This leaves significant gaps for an agent to understand how the tool behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that directly states the tool's purpose without any unnecessary words. It's appropriately sized and front-loaded, making it efficient for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete. It doesn't explain what information is returned about the paper, potential error cases, or how this tool fits within the broader Hugging Face ecosystem alongside its siblings. For a tool with no structured output documentation, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the single parameter 'arxiv_id' clearly documented in the schema. The description adds no additional parameter information beyond what's in the schema, so it meets the baseline of 3 where the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get information') and resource ('specific paper on Hugging Face'), making the purpose immediately understandable. However, it doesn't differentiate this tool from its siblings like 'get-model-info' or 'get-dataset-info' beyond specifying 'paper' as the resource type, which is why it doesn't reach a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With siblings like 'get-daily-papers' (likely for listing papers) and 'search-models' (for different resource types), there's no indication of when this specific paper lookup is appropriate or what distinguishes it from other retrieval tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get-space-infoC
Get detailed information about a specific Space
| Name | Required | Description | Default |
|---|---|---|---|
| space_id | Yes | The ID of the Space (e.g., 'huggingface/diffusers-demo') |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the tool gets 'detailed information' but doesn't specify what that includes (e.g., metadata, statistics, permissions), whether it's read-only or has side effects, or any rate limits or authentication needs. This leaves significant gaps for a tool that likely interacts with external resources.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's appropriately sized and front-loaded, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete. It doesn't explain what 'detailed information' entails (e.g., structure, format), behavioral traits like error handling, or how it differs from sibling tools. For a tool with external dependencies and no structured output, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with the single parameter 'space_id' fully documented in the schema (including an example). The description adds no additional parameter semantics beyond implying it's for a 'specific Space,' which aligns with but doesn't enhance the schema. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('detailed information about a specific Space'), making the purpose understandable. However, it doesn't differentiate this tool from its sibling 'search-spaces' tool, which likely serves a different purpose (searching vs. getting specific details).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'search-spaces' or other 'get-*' siblings (e.g., 'get-model-info'). It mentions 'specific Space' but doesn't clarify prerequisites or exclusions, leaving usage context implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search-collectionsC
Search for collections on Hugging Face Hub
| Name | Required | Description | Default |
|---|---|---|---|
| item | No | Filter by item (e.g., 'models/teknium/OpenHermes-2.5-Mistral-7B') | |
| limit | No | Maximum number of results to return | |
| owner | No | Filter by owner | |
| query | No | Search term for titles and descriptions |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden but lacks behavioral details. It doesn't disclose whether this is a read-only operation, how results are returned (e.g., pagination, format), rate limits, or authentication needs, leaving key traits unspecified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words, making it appropriately sized. However, it could be more front-loaded by immediately clarifying the tool's scope relative to siblings to improve structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a search tool with 4 parameters, no annotations, and no output schema, the description is incomplete. It fails to explain what collections are, how results are structured, or behavioral constraints, leaving significant gaps for an AI agent to use it effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 4 parameters. The description adds no additional meaning beyond what the schema provides, such as explaining how parameters interact (e.g., combining query with owner) or usage examples, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action ('Search for') and resource ('collections on Hugging Face Hub'), which is clear but vague. It doesn't specify what collections are (e.g., curated sets of models/datasets) or differentiate from siblings like search-datasets or search-models, leaving the scope ambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. With siblings like search-datasets and search-models, it's unclear if this is for broader searches or specific to collection types, and there are no prerequisites or exclusions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search-datasetsC
Search for datasets on Hugging Face Hub
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Filter by tags | |
| limit | No | Maximum number of results to return | |
| query | No | Search term | |
| author | No | Filter by author/organization |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure but only states the basic action. It doesn't mention whether this is a read-only operation, how results are returned (format, pagination), rate limits, authentication requirements, or error conditions. The description is minimal and lacks essential behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—a single sentence with no wasted words. It's front-loaded with the core purpose and efficiently communicates the essential action and target resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with 4 parameters and no annotations or output schema, the description is insufficient. It doesn't explain what constitutes a dataset on Hugging Face Hub, how results are structured, or typical use cases. The agent lacks context about what to expect from this operation beyond the basic action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no parameter information beyond what's already in the schema (which has 100% coverage). It doesn't explain how parameters interact, provide examples, or clarify semantics like tag format or author filtering behavior. With complete schema coverage, the baseline is 3, but the description doesn't enhance understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Search for') and resource ('datasets on Hugging Face Hub'), making the tool's purpose immediately understandable. However, it doesn't differentiate this tool from its sibling search tools (search-collections, search-models, search-spaces) beyond specifying the dataset resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like get-dataset-info or other search tools. It doesn't mention prerequisites, typical use cases, or exclusions, leaving the agent to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search-modelsC
Search for models on Hugging Face Hub
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Filter by tags (e.g., 'text-classification', 'translation') | |
| limit | No | Maximum number of results to return | |
| query | No | Search term (e.g., 'bert', 'gpt') | |
| author | No | Filter by author/organization (e.g., 'huggingface', 'google') |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure but offers minimal information. It states it's a search operation but doesn't describe what the search returns (e.g., list of models with metadata), whether there are rate limits, authentication requirements, pagination behavior, or how results are sorted. For a search tool with zero annotation coverage, this leaves significant gaps in understanding how it behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that gets straight to the point with zero wasted words. It's appropriately sized for a search tool and front-loads the essential information (search operation + target resource). Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no annotations and no output schema, the description is insufficiently complete. It doesn't explain what the search returns (model metadata, IDs, etc.), how results are structured, or any behavioral constraints. For a search tool that presumably returns multiple results, more context about the response format and operational characteristics would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with clear documentation for all 4 parameters (query, author, tags, limit). The description adds no additional parameter information beyond what's already in the schema. According to scoring rules, when schema_description_coverage is high (>80%), the baseline is 3 even with no param info in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Search for') and resource ('models on Hugging Face Hub'), making the purpose immediately understandable. However, it doesn't differentiate this tool from sibling search tools like 'search-collections', 'search-datasets', and 'search-spaces', which all follow the same pattern but target different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when to choose this over 'get-model-info' (which presumably retrieves details for a specific model) or other search tools for different resource types. There's no context about prerequisites, typical use cases, or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search-spacesC
Search for Spaces on Hugging Face Hub
| Name | Required | Description | Default |
|---|---|---|---|
| sdk | No | Filter by SDK (e.g., 'streamlit', 'gradio', 'docker') | |
| tags | No | Filter by tags | |
| limit | No | Maximum number of results to return | |
| query | No | Search term | |
| author | No | Filter by author/organization |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but offers minimal behavioral insight. It doesn't disclose whether this is a read-only operation, what authentication might be required, rate limits, pagination behavior, or what the output format looks like (especially problematic since there's no output schema). The description only states what it does, not how it behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that states the core purpose without any wasted words. It's appropriately sized for a search tool and front-loads the essential information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is insufficiently complete. For a search tool with 5 parameters, it should provide more context about what 'Spaces' are, typical use cases, and what information the search returns. The description doesn't compensate for the missing structured data that would help an agent understand the tool's behavior and output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, providing clear documentation for all 5 parameters. The description adds no additional parameter information beyond what's in the schema, so it meets the baseline of 3 where the schema does the heavy lifting but doesn't compensate with extra context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Search for') and resource ('Spaces on Hugging Face Hub'), making the purpose immediately understandable. It distinguishes from most siblings (e.g., search-datasets, search-models) by specifying 'Spaces', though it doesn't explicitly differentiate from non-search siblings like get-space-info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It doesn't mention when to prefer search-spaces over get-space-info for retrieving information about a specific space, or how it relates to other search tools like search-datasets. The description offers no context about typical use cases or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
10 tool updates
v0.1.0- First observed
get-collection-info - First observed
get-daily-papers - First observed
get-dataset-info - First observed
get-model-info - First observed
get-paper-info - First observed
get-space-info - First observed
search-collections - First observed
search-datasets - First observed
search-models - First observed
search-spaces
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.
Maintenance
Related MCP Connectors
Search hub knowledge and memories, read saved context, and create or update hub content.
Verified open AI artifact search, trust evidence, downloads, and agent workflows from Hugging Bay.
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
Search GitHub, npm, PyPI, StackOverflow, ArXiv from one MCP — built for coding agents.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables interaction with the Hugging Face Dataset Viewer API, allowing users to browse, search, filter, and analyze datasets hosted on the Hugging Face Hub.831MIT
- FlicenseAqualityDmaintenanceEnables 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.8-
- AlicenseNot gradedqualityDmaintenanceEnables searching, fetching, and analyzing scientific papers from ArXiv, ACL Anthology, Semantic Scholar, and Hugging Face datasets, with optional LLM-powered document QA and research proposal workflows.92Apache 2.0
- 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