Por Prof. AMR. Em, 19/09/2025
Hugging Face Official MCP Server 🤗
Link: Hugging Face MCP Server
O que é?
O Hugging Face MCP Server é uma implementação do Machine Communication Protocol (MCP) que atua como um servidor para integrar Modelos de Linguagem Grandes (LLMs) com o Hugging Face Hub e milhares de Aplicações de IA construídas com Gradio . Ele fornece as implementações necessárias dos endpoints da API do Hub e de busca .
Para que serve?
Sua principal função é permitir que LLMs se conectem ao Hugging Face Hub e a milhares de Aplicações de IA . Ele serve como uma ponte essencial, possibilitando o acesso a modelos, datasets, Spaces, artigos e coleções hospedados no Hugging Face diretamente de dentro de projetos de LLM .
Como funciona?
O servidor opera seguindo o protocolo MCP, comunicando-se com clientes MCP através de diferentes métodos de transporte. Ele suporta:
- STDIO (Standard Input/Output)
- SSE (Server-Sent Events)
- StreamableHTTP
- StreamableHTTP em modo JSON (StreamableHTTPJson)
A comunicação com o servidor geralmente requer autenticação, realizada através de um token de autorização Hugging Face, como o seu <YOUR_HF_TOKEN>, enviado via cabeçalho Authorization . A configuração do servidor pode ser gerenciada por meio de variáveis de ambiente ou arquivos de configuração, como mcp.json . Os transportes SSE e StreamableHTTP são stateful, mantendo uma conexão com o cliente MCP .
Instruções de Uso
Instalação em Clientes de LLM
- Claude Desktop ou claude.ai: Clique no link para adicionar o conector Hugging Face à sua conta ou navegue até https://claude.ai/settings/connectors e adicione "Hugging Face" da galeria .
- Claude Code: Use o comando claude mcp add hf-mcp-server -t http https://huggingface.co/mcp ? login e siga as instruções para autenticação. Alternativamente, forneça o token: claude mcp add hf-mcp-server -t http https://huggingface.co/mcp -H "Authorization: Bearer <YOUR_HF_TOKEN>" .
- VSCode: Clique no link para adicionar o conector ou instale pela galeria em https://code.visualstudio.com/mcp. Para configuração manual, adicione o seguinte snippet ao seu mcp.json: json<button><svg><path></path></svg><span>Copy code</span><span></span></button>
"huggingface" : { "url" : "https://huggingface.co/mcp", "headers" : { "Authorization" : "Bearer <YOUR_HF_TOKEN>" } } - Cursor: Instale diretamente no Cursor ou use um snippet similar ao do VSCode no seu mcp.json .
Após a instalação, navegue até https://huggingface.co/settings/mcp para configurar suas Ferramentas (Tools) e Espaços (Spaces) .
Executando Localmente
- Via npx:
- Para iniciar em modo STDIO: npx @llmindset/hf-mcp-server
- Para iniciar em modo Streamable HTTP: npx @llmindset/hf-mcp-server-http
- Para iniciar em modo Streamable HTTP (JSON RPC): npx @llmindset/hf-mcp-server-json
- Via Docker:
- Baixe a imagem mais recente: docker pull ghcr.io/evalstate/hf-mcp-server:latest
- Execute o contêiner, mapeando a porta 3000: docker run --rm -p 3000:3000 ghcr.io/evalstate/hf-mcp-server:latest .
Configuração Geral
- Token Hugging Face (DEFAULT_HF_TOKEN): Essencial para autenticar requisições. Configure-o no cliente MCP ou via variável de ambiente DEFAULT_HF_TOKEN. Use apenas em ambientes de desenvolvimento/teste ou implantações locais .
- Variáveis de Ambiente: Controle o comportamento do servidor com variáveis como TRANSPORT (stdio, sse, streamableHttp, streamableHttpJson) e HF_API_TIMEOUT .
- Endpoints de Transporte:
- SSE: /sse (com endpoint de mensagem em /message)
- Streamable HTTP: /mcp (regular ou JSON)
- STDIO: Usa stdin/stdout diretamente.
- Interface de Gerenciamento: Geralmente acessível em http://localhost:3000/ .