HuggingFace Spaces

Servidor para usar HuggingFace Spaces, suportando Imagens, Áudio, Texto e mais. Modo Claude Desktop para facilidade de uso.

GitHub
388
Experimente este MCPPatrocinado

Documentação

mcp-hfspace MCP Server 🤗

[!TIP]

Você pode acessar e configurar os serviços MCP do Hugging Face diretamente em https://hf.co/mcp,, incluindo espaços Gradio.

Este projeto foi substituído pelo Hugging Face MCP Server oficial e pelos Gradio MCP Endpoints.

Alternativamente, você pode executar o hf-mcp-server localmente como um servidor STDIO, ou com suporte robusto para SSE, HTTP de Streaming e Modo JSON de HTTP de Streaming. Isso também executa uma UI local para selecionar ferramentas e endpoints e suporta ToolListChangedNotifications também.

hf.co/mcp

image

mcp-hfspace

Leia a introdução aqui llmindset.co.uk/resources/mcp-hfspace/

Conecte-se aos Hugging Face Spaces com configuração mínima necessária - basta adicionar seus espaços e pronto!

Por padrão, ele se conecta a black-forest-labs/FLUX.1-schnell fornecendo recursos de Geração de Imagens para o Claude Desktop.

Default Setup

Suporte MCP do Gradio

[!TIP] O Gradio 5.28 agora tem suporte MCP integrado via SSE: https://huggingface.co/blog/gradio-mcp. Verifique se o seu Space alvo está habilitado para MCP!

Instalação

O pacote NPM é @llmindset/mcp-hfspace.

Instale uma versão recente do NodeJS para sua plataforma e adicione o seguinte à seção mcpServers do seu arquivo claude_desktop_config.json:

    "mcp-hfspace": {
      "command": "npx",
      "args": [
        "-y",
        "@llmindset/mcp-hfspace"
      ]
    }

Certifique-se de estar usando o Claude Desktop 0.78 ou superior.

Isso permitirá que você comece com um Gerador de Imagens.

Configuração básica

Forneça uma lista de espaços HuggingFace nos argumentos. O mcp-hfspace encontrará o endpoint mais apropriado e o configurará automaticamente para uso. Um exemplo de claude_desktop_config.json é fornecido abaixo.

Por padrão, o diretório de trabalho atual é usado para upload/download de arquivos. No Windows, esta é uma pasta de leitura/gravação em \users\<username>\AppData\Roaming\Claude\<version.number\, e no MacOS é a raiz somente leitura: /.

É recomendado substituir isso e definir um Diretório de Trabalho para lidar com o upload e download de imagens e outros conteúdos baseados em arquivos. Especifique o argumento --work-dir=/your_directory ou a variável de ambiente MCP_HF_WORK_DIR.

Um exemplo de configuração para usar um gerador de imagens moderno, modelo de visão e texto para fala, com um diretório de trabalho definido, está abaixo:

    "mcp-hfspace": {
      "command": "npx",
      "args": [
        "-y",
        "@llmindset/mcp-hfspace",
        "--work-dir=/Users/evalstate/mcp-store",
        "shuttleai/shuttle-jaguar",
        "styletts2/styletts2",
        "Qwen/QVQ-72B-preview"
      ]
    }

Para usar espaços privados, forneça seu Token do Hugging Face com o argumento --hf-token=hf_... ou a variável de ambiente HF_TOKEN.

É possível executar várias instâncias do servidor para usar diferentes diretórios de trabalho e tokens, se necessário.

Manipulação de Arquivos e Modo Claude Desktop

Por padrão, o Servidor opera no Modo Claude Desktop. Neste modo, as Imagens são retornadas nas respostas das ferramentas, enquanto outros arquivos são salvos na pasta de trabalho, e seu caminho de arquivo é retornado como uma mensagem. Isso geralmente proporciona a melhor experiência se você estiver usando o Claude Desktop como cliente.

URLs também podem ser fornecidas como entradas: o conteúdo é passado para o Space.

Há um prompt "Available Resources" que fornece ao Claude os arquivos disponíveis e tipos mime do seu diretório de trabalho. Esta é atualmente a melhor maneira de gerenciar arquivos.

Exemplo 1 - Geração de Imagens (Baixar Imagem / Visão do Claude)

Usaremos o Claude para comparar imagens criadas por shuttleai/shuttle-3.1-aesthetic e FLUX.1-schnell. As imagens são salvas no Diretório de Trabalho, além de serem incluídas na janela de contexto do Claude - para que o Claude possa usar seus recursos de visão.

Image Generation Comparison

Exemplo 2 - Modelo de Visão (Enviar Imagem)

Usaremos merve/paligemma2-vqav2 link do space para consultar uma imagem. Neste caso, especificamos o nome do arquivo que está disponível no Diretório de Trabalho: não queremos enviar a Imagem diretamente para a janela de contexto do Claude. Então, podemos solicitar ao Claude:

use paligemma to find out who is in "test_gemma.jpg" -> Text Output: david bowie Vision - File Upload

Se você estiver enviando algo para o contexto do Claude, use o botão de Anexo com Clipe de Papel; caso contrário, especifique o nome do arquivo para o Servidor enviar diretamente.

Também podemos fornecer uma URL. Por exemplo: use paligemma to detect humans in https://e3.365dm.com/24/12/1600x900/skynews-taylor-swift-eras-tour_6771083.jpg?20241209000914 -> One person is detected in the image - Taylor Swift on stage.

Exemplo 3 - Texto para Fala (Baixar Áudio)

No Modo Claude Desktop, o arquivo de áudio é salvo no WORK_DIR, e o Claude é notificado da criação. Se não estiver no modo desktop, o arquivo é retornado como um recurso codificado em base64 para o Cliente (útil se ele suportar anexos de Áudio incorporados).

Voice Production

Exemplo 4 - Fala para Texto (Enviar Áudio)

Aqui, usamos hf-audio/whisper-large-v3-turbo para transcrever algum áudio e disponibilizá-lo para o Claude.

Audio Transcribe

Exemplo 5 - Imagem para Imagem

Neste exemplo, especificamos o nome do arquivo para microsoft/OmniParser usar, e recebemos de volta uma Imagem anotada e 2 textos separados: descrições e coordenadas. O prompt usado foi use omniparser to analyse ./screenshot.png e use the analysis to produce an artifact that reproduces that screen. DawnC/Pawmatch também é bom nisso.

Omniparser and Artifact

Exemplo 6 - Chat

Neste exemplo, o Claude define uma série de quebra-cabeças de raciocínio para o Qwen e faz perguntas de acompanhamento para esclarecimento.

Qwen Reasoning Test

Especificando o Endpoint da API

Se necessário, você pode especificar um Endpoint de API específico adicionando-o ao nome do space. Então, em vez de passar Qwen/Qwen2.5-72B-Instruct, você usaria Qwen/Qwen2.5-72B-Instruct/model_chat.

Modo Claude Desktop

Isso pode ser desabilitado com a opção --desktop-mode=false ou a variável de ambiente CLAUDE_DESKTOP_MODE=false. Neste caso, o conteúdo é retornado como um Recurso incorporado codificado em Base64.

Spaces Recomendados

Alguns spaces recomendados para experimentar:

Geração de Imagens

  • shuttleai/shuttle-3.1-aesthetic
  • black-forest-labs/FLUX.1-schnell
  • yanze/PuLID-FLUX
  • gokaygokay/Inspyrenet-Rembg (Remoção de Fundo)
  • diyism/Datou1111-shou_xin - Lindos Desenhos a Lápis

Chat

  • Qwen/Qwen2.5-72B-Instruct
  • prithivMLmods/Mistral-7B-Instruct-v0.3

Texto para fala / Geração de Áudio

  • fantaxy/Sound-AI-SFX
  • parler-tts/parler_tts

Fala para texto

  • hf-audio/whisper-large-v3-turbo
  • (os modelos openai usam parâmetros sem nome, então não funcionarão)

Texto para música

  • haoheliu/audioldm2-text2audio-text2music

Tarefas de Visão

  • microsoft/OmniParser
  • merve/paligemma2-vqav2
  • merve/paligemma-doc
  • DawnC/PawMatchAI
  • DawnC/PawMatchAI/on_find_match_click - para recomendações interativas de cães

Outros Recursos

Prompts

Prompts para cada Space são gerados e fornecem uma oportunidade de entrada. Tenha em mente que, muitas vezes, os Spaces não são configurados com rótulos particularmente úteis, etc. O Claude é na verdade muito bom em descobrir isso, e a descrição da Ferramenta é bastante rica (mas não visível no Claude Desktop).

Recursos

Uma lista de arquivos no WORK_DIR é retornada e, por conveniência, retorna o nome como texto "Use o arquivo...". Se você quiser adicionar algo ao contexto do Claude, use o clipe de papel - caso contrário, especifique o nome do arquivo para o Servidor MCP. O Claude não suporta transmitir recursos de dentro do Contexto.

Spaces Privados

Spaces Privados são suportados com um token do HuggingFace. O Token é usado para baixar e salvar conteúdo gerado.

Usando o Claude Desktop

Para usar com o Claude Desktop, adicione a configuração do servidor:

No MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json No Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mcp-hfspace": {
      "command": "npx"
      "args": [
        "-y",
        "@llmindset/mcp-hfspace",
        "--work-dir=~/mcp-files/ or x:/temp/mcp-files/",
        "--HF_TOKEN=HF_{optional token}"
        "Qwen/Qwen2-72B-Instruct",
        "black-forest-labs/FLUX.1-schnell",
        "space/example/specific-endpint"
        (... and so on)
        ]
    }
  }
}

Problemas Conhecidos e Limitações

mcp-hfspace

  • Endpoints com parâmetros sem nome não são suportados no momento.
  • Tradução completa de alguns tipos complexos de Python para formatos MCP adequados.

Claude Desktop

  • O Claude Desktop 0.75 parece não responder a erros do Servidor MCP, expirando em vez disso. Para problemas persistentes, use o MCP Inspector para ter uma visão melhor do diagnóstico do que está dando errado. Se algo parar de funcionar de repente, provavelmente é devido ao esgotamento da sua cota ZeroGPU do HuggingFace - tente novamente após um curto período, ou configure seu próprio Space para hospedagem.
  • O Claude Desktop parece usar um valor de timeout fixo de 60s e não parece usar Notificações de Progresso para gerenciar UX ou keep-alive. Se você estiver usando spaces ZeroGPU, trabalhos grandes/pesados podem expirar. Verifique o WORK_DIR para resultados; o Servidor MCP ainda capturará e salvará o resultado se ele foi produzido.
  • O relatório do Claude Desktop sobre Status do Servidor, logs, etc. não é ótimo - use @modelcontextprotocol/inspector para ajudar a diagnosticar problemas.

HuggingFace Spaces

  • Se as cotas ou filas do ZeroGPU estiverem muito longas, tente duplicar o space. Se o seu trabalho levar menos de sessenta segundos, você geralmente pode alterar o decorador de função @spaces.GPU(duration=20) em app.py para solicitar menos cota ao executar o trabalho.
  • Passar HF_TOKEN fará com que as cotas ZeroGPU se apliquem à sua conta HF (Pro)
  • Se você tiver um space privado e hardware dedicado, seu HF_TOKEN dará acesso direto a isso - nenhuma cota se aplica. Recomendo isso se você estiver usando para qualquer tipo de tarefa de Produção.

Serviços MCP de Terceiros

mcp-hfspace MCP server