docs/hf_mcp_setup.md

Hugging Face MCP Server Setup

The Hugging Face MCP (Model Context Protocol) Server lets your editor or chat-based assistant access Hub search and Spaces tools. Because the configuration snippet is generated per account and per client, you need to complete a few manual steps.

1. Generate your MCP client snippet

1. Sign in to your Hugging Face account.
2. Visit the MCP settings page: https://huggingface.co/settings/mcp.
3. Choose your client from the list (VS Code, Cursor, Zed, Claude Desktop, etc.).
4. Copy the configuration block that Hugging Face provides. It contains the exact command, arguments, and environment variables required for your client.

Why this matters: the settings portal encodes account-specific tokens, optional Spaces tools, and client-specific syntax. Using the generated snippet avoids guesswork and prevents credential leaks.

2. Store credentials securely

• Hugging Face supplies an access token in the snippet. Treat it as a secret.
• Prefer reading the token from an environment variable (for example HF_TOKEN) instead of hard-coding it. Most clients support ${env:VAR_NAME} or process.env.VAR_NAME substitution.
• If you need a new token, create one at https://huggingface.co/settings/tokens with the “MCP Server” scope.

3. Apply the snippet to your client

The exact location depends on the tool you use. Common examples:

• VS Code (GitHub Copilot or Continue extension): Add the snippet to your MCP configuration file, typically settings.json under the "mcpServers" key, then reload the window.
• Cursor or Zed: Paste the config into their MCP settings pane, save, and restart the application.
• Claude Desktop: edit ~/.anthropic/claude_desktop/config.json (or use the UI) to include the new server block.

After restarting, you should see a "Hugging Face" (or similar) MCP server listed in the client, and you can invoke commands like searching models or running MCP-enabled Spaces.

4. (Optional) Add community Spaces tools

You can extend the server with MCP-compatible Gradio Spaces:

1. Browse MCP-enabled Spaces: https://huggingface.co/spaces?filter=mcp-server.
2. Back on https://huggingface.co/settings/mcp, add the Space to your configuration.
3. Refresh or restart your client so it picks up the new tools.

5. Troubleshooting tips

• If the client can’t connect, double-check that the command path in the snippet matches your environment (e.g., Python virtual environment or huggingface-cli).
• Regenerate the snippet if you rotate tokens or remove Spaces tools.
• Consult Hugging Face’s documentation for deeper guidance: https://huggingface.co/docs/hub/en/hf-mcp-server.

This repository does not include static MCP configuration files because the values are account-specific. Use this guide alongside your generated snippet to finish the setup quickly.