Skip to content
Get packs

Guide · Agent skill

How to use the Hugging Face Hub via MCP agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The hf-mcp skill lets an AI assistant query the Hugging Face Hub through the Hugging Face MCP server, a standard connector that gives the assistant extra tools. This guide explains what the skill does, how to install it, how to trigger it with plain requests, and what it needs before it works. By the end you will be able to search models and papers, read documentation, call Gradio Spaces, and launch compute jobs from your chat.

Hugging Face Hub via MCPhuggingface/skills · Apache-2.0

Quick start

  1. 1Connect the MCP server. Set up the Hugging Face MCP server for your account at huggingface.co/settings/mcp and connect it to your AI client.
  2. 2Create an access token. Prepare a Hugging Face access token as HF_TOKEN if you need private repos or jobs.
  3. 3Download the skill ZIP. Download the hf-mcp ZIP from this page.
  4. 4Unzip into a skills folder. Unzip it into ~/.claude/skills/ for personal use or .claude/skills/ inside a project.
  5. 5Or upload in Claude apps. In the Claude apps, go to Settings → Capabilities → Skills and upload the ZIP.
  6. 6Ask a plain-language question. Request something like finding a model or comparing two models, without naming the tool.
  7. 7Check results and job status. Review the returned repo details, and ask for job status or logs when running compute jobs.

What is the hf-mcp skill and what does it let the agent do?

An agent skill is a folder with a SKILL.md file that tells an AI assistant when and how to use a set of tools. The hf-mcp skill covers the Hugging Face Hub tools exposed by the Hugging Face MCP server. Once installed and connected, the agent can search for models, datasets, Spaces and research papers, and pull up repo details and model card documentation.

It can also fetch library documentation, call Gradio Spaces as tools (for example image generation or speech-to-text), and run compute jobs on CPU or GPU hardware with status and log checks.

  • Search models, datasets, Spaces and papers on the Hub
  • Read repo details and full READMEs, including model cards
  • Search and fetch Hugging Face library documentation
  • Use Gradio Spaces as tools, for example for image generation or transcription
  • Launch jobs on CPU or GPU hardware and check their status and logs

Connect the Hugging Face MCP server first

The skill only works when the Hugging Face MCP server is connected to your assistant. It does not run locally on its own. Setup instructions are at https://huggingface.co/settings/mcp.

If you want the agent to read private repos or run jobs that need your account, you also need a Hugging Face access token, referred to as HF_TOKEN in the skill.

Install the hf-mcp skill

Download the ZIP for this skill from this page and unzip it. The skill is a folder containing SKILL.md. Place that folder in one of these locations:

  • Personal skills: ~/.claude/skills/
  • Project skills: .claude/skills/ inside your project folder
  • Claude apps: upload the ZIP under Settings → Capabilities → Skills
~/.claude/skills/hf-mcp/SKILL.md

Trigger the skill with natural requests

You do not need to name the skill or any tool. Ask in plain language and describe the goal. The skill's description covers searching models, datasets, Spaces and papers, getting repo details, fetching documentation, running compute jobs, and using Gradio Spaces as AI tools, so requests on those topics are the ones that should trigger it.

Examples of requests that match the skill's coverage:

  • "Find the best model for code generation"
  • "Compare Llama vs Qwen for text generation"
  • "Find datasets for sentiment analysis in English"
  • "What are the latest papers on RLHF?"
  • "How do I fine-tune with LoRA using PEFT?"
  • "Run this Python script on a GPU"
  • "What's happening with my training job?"

Examples of what the agent does behind the scenes

For a model search, the source shows the agent calling model_search with a task and query, then calling hub_repo_details on the top result with include_readme set to true. For a comparison, it runs one search per provider and then fetches details for both models.

For a GPU job, the agent calls hf_jobs with an image, a command, and a flavor such as a10g-small. The source shows a training example that passes HF_TOKEN as a secret. Job status is checked with hf_jobs using the ps and logs operations.

  • Trending models: model_search with sort set to trendingScore
  • Popular options: model_search with sort set to downloads
  • Find Spaces usable as tools: space_search with mcp set to true
  • Check your login: hf_whoami
hf_jobs(operation="ps") hf_jobs(operation="logs", args={"job_id": "job-xxxxx"})

Safety notes: scripts, network and secrets

This skill does not run scripts on your machine. It does use the network, because it queries the live Hub and remote Spaces. Do not use it for tasks that must stay fully offline or private.

Job runs can receive your HF_TOKEN as a secret, and jobs can use paid compute credits. Review the flavor and the script before you ask the agent to launch a job. The skill is licensed under Apache-2.0.

  • Jobs with private repos need HF_TOKEN passed as a secret
  • GPU flavors such as a10g-small likely require paid compute credits
  • Check job status and logs to see what is running

Tips for better results

Name the outcome you want and let the agent pick the tools. If you care about recency, ask for trending models. If you care about proven options, ask for the most downloaded ones.

  • Use sort="trendingScore" to find what is popular now
  • Use sort="downloads" to find widely used options
  • Ask for include_readme when you want full model or dataset documentation
  • Ask for Spaces that work as tools to get callable AI apps
  • Ask the agent to list available Space-based tasks with the discover operation

What people use it for

  • Compare open models from different providers for a text generation task before choosing one.
  • Find training datasets for a task such as English sentiment analysis.
  • Look up recent research papers and the models linked to them.
  • Run a training or inference script on a cloud GPU and check its logs from chat.
  • Transcribe audio or generate images by calling a Gradio Space as a tool.

Frequently asked questions

How do I install the hf-mcp skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use or into .claude/skills/ in a project. In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.

What do I need to use the hf-mcp skill?

You need a Hugging Face account connected to the HF MCP server, set up at huggingface.co/settings/mcp, and an MCP-compatible AI client. A Hugging Face access token (HF_TOKEN) is needed for private repos and jobs, and GPU job flavors likely require paid compute credits.

Is the hf-mcp skill free?

The skill is licensed under Apache-2.0. The source does not state pricing for the Hugging Face MCP server itself, but GPU job flavors such as a10g-small likely use paid compute credits.

Does the skill run code on my computer?

No. The skill does not run scripts locally and only works when the Hugging Face MCP server is connected. It does use the network to query the live Hub and remote Spaces.

Can the agent use my Hugging Face token to run jobs?

Job runs can receive HF_TOKEN as a secret, which is needed for private repos. Only allow this if you are comfortable with the agent using your token and spending compute credits.

Is there an alternative if I do not want to use an MCP server?

The source does not describe alternatives. You can use the Hugging Face website directly to search the Hub, or use the Hugging Face libraries and documentation in your own code. This skill is specific to the Hugging Face ecosystem and is not a general coding helper.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Choose the hf-mcp skill if you are an ML engineer, researcher, developer or student who wants to search the Hugging Face Hub, read model documentation, and launch GPU jobs from your AI assistant. Pick something else if you need fully offline or private work, or if you do not want an agent using your Hugging Face token and compute credits.

Download the skill