mcp-hfspace MCP 서버 🤗

여기에서 소개를 읽어보세요 llmindset.co.uk/resources/mcp-hfspace/

최소한의 설정만으로 Hugging Face Spaces 에 연결하세요. 간단히 공간을 추가하고 시작하세요!

기본적으로 evalstate/FLUX.1-schnell 에 연결하여 Claude Desktop에 이미지 생성 기능을 제공합니다.

설치

NPM 패키지는 @llmindset/mcp-hfspsace 입니다.

플랫폼에 맞는 최신 버전의 NodeJS를 설치한 다음 claude_desktop_config.json 파일의 mcpServers 섹션에 다음을 추가합니다.

지엑스피1

Claude Desktop 0.78 이상을 사용하고 있는지 확인하세요.

이렇게 하면 이미지 생성기를 시작할 수 있습니다.

기본 설정

인수에 HuggingFace 공간 목록을 제공하세요. mcp-hfspace는 가장 적합한 엔드포인트를 찾아 자동으로 사용하도록 구성합니다. 아래에 claude_desktop_config.json 의 예가 나와 있습니다.

기본적으로 현재 작업 디렉터리는 파일 업로드/다운로드에 사용됩니다. Windows에서는 \users\<username>\AppData\Roaming\Claude\<version.number\ 에 읽기/쓰기 권한이 있는 폴더가 있고, MacOS에서는 읽기 전용 루트인 / 에 있습니다.

이 설정을 재정의하고 이미지 및 기타 파일 기반 콘텐츠의 업로드 및 다운로드를 처리할 작업 디렉터리를 설정하는 것이 좋습니다. --work-dir=/your_directory 인수 또는 MCP_HF_WORK_DIR 환경 변수를 지정하세요.

최신 이미지 생성기, 비전 모델 및 텍스트 음성 변환을 사용하기 위한 구성 예는 아래와 같으며 작업 디렉토리 세트는 아래와 같습니다.

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

개인 공간을 사용하려면 --hf-token=hf_... 인수나 HF_TOKEN 환경 변수와 함께 Hugging Face Token을 제공하세요.

필요한 경우 다른 작업 디렉토리와 토큰을 사용하기 위해 여러 서버 인스턴스를 실행할 수 있습니다.

파일 처리 및 Claude 데스크톱 모드

기본적으로 서버는 Claude Desktop 모드 로 작동합니다. 이 모드에서 이미지는 도구 응답으로 반환되고, 다른 파일은 작업 폴더에 저장되며, 파일 경로는 메시지로 반환됩니다. Claude Desktop을 클라이언트로 사용할 경우 일반적으로 이 모드가 최상의 환경을 제공합니다.

URL을 입력으로 제공할 수도 있습니다. 콘텐츠는 Space로 전달됩니다.

Claude에게 작업 디렉터리에서 사용 가능한 파일과 MIME 유형을 알려주는 "사용 가능한 리소스" 프롬프트가 있습니다. 현재로서는 이것이 파일을 관리하는 가장 좋은 방법입니다.

예제 1 - 이미지 생성(이미지 다운로드/Claude Vision)

Claude를 사용하여 shuttleai/shuttle-3.1-aesthetic 과 FLUX.1-schnell 로 생성된 이미지를 비교해 보겠습니다. 이미지는 작업 디렉터리에 저장되고 Claude의 컨텍스트 창에도 포함되어 Claude가 비전 기능을 사용할 수 있도록 합니다.

예제 2 - 비전 모델(이미지 업로드)

merve/paligemma2-vqav2 공간 링크를 사용하여 이미지를 쿼리하겠습니다. 이 경우 작업 디렉터리에서 사용 가능한 파일 이름을 지정합니다. 이미지를 Claude의 컨텍스트 창에 직접 업로드하지 않기 때문입니다. 따라서 Claude에게 다음과 같이 묻습니다.

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

Claude의 컨텍스트에 무언가를 업로드하는 경우 Paperclip Attachment 버튼을 사용하고, 그렇지 않은 경우 서버에서 직접 보낼 파일 이름을 지정하세요.

URL도 제공해 드릴 수 있습니다. 예: 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.

예제 3 - 텍스트 음성 변환(오디오 다운로드)

Claude 데스크톱 모드 에서는 오디오 파일이 WORK_DIR에 저장되고 Claude에게 생성 알림이 전송됩니다. 데스크톱 모드가 아닌 경우, 파일은 base64로 인코딩된 리소스 형태로 클라이언트에 반환됩니다(임베디드 오디오 첨부 파일을 지원하는 경우 유용함).

예제 4 - 음성-텍스트 변환(오디오 업로드)

여기에서는 hf-audio/whisper-large-v3-turbo 사용하여 일부 오디오를 필사하여 Claude가 사용할 수 있도록 합니다.

예제 5 - 이미지 대 이미지

이 예제에서는 microsoft/OmniParser 에서 사용할 파일 이름을 지정하고, 주석이 달린 이미지와 설명 및 좌표라는 두 개의 별도 텍스트를 반환합니다. 사용된 프롬프트는 use omniparser to analyse ./screenshot.png , use the analysis to produce an artifact that reproduces that screen 었습니다. DawnC/Pawmatch 도 이 작업에 능숙합니다.

예제 6 - 채팅

이 예에서 클로드는 웬에게 여러 가지 추론 퍼즐을 제시하고, 이를 명확히 하기 위해 후속 질문을 합니다.

API 엔드포인트 지정

필요한 경우, spacename에 특정 API 엔드포인트를 추가하여 지정할 수 있습니다. 따라서 Qwen/Qwen2.5-72B-Instruct 전달하는 대신 Qwen/Qwen2.5-72B-Instruct/model_chat 사용하면 됩니다.

클로드 데스크톱 모드

이 기능은 --desktop-mode=false 옵션이나 CLAUDE_DESKTOP_MODE=false 환경 변수를 사용하여 비활성화할 수 있습니다. 이 경우 콘텐츠는 Base64로 인코딩된 임베디드 리소스로 반환됩니다.

기타 기능

프롬프트

각 스페이스에 대한 프롬프트가 생성되어 입력할 수 있습니다. 스페이스가 특별히 유용한 라벨 등으로 구성되어 있지 않은 경우가 많다는 점을 유의하세요. Claude는 이 부분을 매우 잘 이해하고 있으며, 도구 설명도 매우 풍부합니다(하지만 Claude Desktop에서는 표시되지 않습니다).

자원

WORK_DIR에 있는 파일 목록이 반환되고, 편의상 파일 이름이 "파일 사용..." 텍스트로 반환됩니다. Claude의 컨텍스트에 무언가를 추가하려면 클립을 사용하고, 그렇지 않으면 MCP 서버의 파일 이름을 지정하세요. Claude는 컨텍스트 내에서 리소스 전송을 지원하지 않습니다.

개인 공간

프라이빗 스페이스는 HuggingFace 토큰으로 지원됩니다. 이 토큰은 생성된 콘텐츠를 다운로드하고 저장하는 데 사용됩니다.

Claude Desktop 사용

Claude Desktop과 함께 사용하려면 서버 구성을 추가하세요.

MacOS의 경우: ~/Library/Application Support/Claude/claude_desktop_config.json 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)
        ]
    }
  }
}

알려진 문제 및 제한 사항

mcp-hfspace

현재로선 이름이 지정되지 않은 매개변수가 있는 엔드포인트는 지원되지 않습니다.
일부 복잡한 Python 유형을 적합한 MCP 형식으로 완전히 번역합니다.

클로드 데스크탑

Claude Desktop 0.75가 MCP 서버 오류에 응답하지 않고 시간 초과가 발생하는 것 같습니다. 문제가 지속되는 경우 MCP Inspector를 사용하여 문제 원인을 자세히 진단해 보세요. 갑자기 작동이 중단되면 HuggingFace ZeroGPU 할당량이 소진되었을 가능성이 높습니다. 잠시 후 다시 시도하거나 호스팅을 위한 자체 공간을 설정하세요.
Claude Desktop은 60초의 고정 시간 초과 값을 사용하는 것으로 보이며, UX 관리나 Keep-Alive를 위해 진행률 알림을 사용하지 않는 것으로 보입니다. ZeroGPU 공간을 사용하는 경우, 크고 무거운 작업이 시간 초과될 수 있습니다. 하지만 WORK_DIR에서 결과를 확인하세요. MCP 서버는 생성된 결과를 캡처하여 저장합니다.
Claude Desktops에서 서버 상태, 로깅 등을 보고하는 기능은 그다지 좋지 않습니다. @modelcontextprotocol/inspector를 사용하여 문제를 진단해 보세요.

허깅페이스 스페이스

ZeroGPU 할당량이나 대기열이 너무 길면 공간을 복제해 보세요. 작업 시간이 60초 미만이면 일반적으로 app.py 에서 함수 데코레이터 @spaces.GPU(duration=20) 변경하여 작업 실행 시 할당량을 줄일 수 있습니다.
HuggingFace Pro 계정이 있는 경우 Gradio API는 ZeroGPU 작업에 대한 추가 견적을 제공하지 않습니다. 이를 위해서는 X-IP-Token 헤더를 설정해야 합니다.
개인 공간과 전용 하드웨어가 있는 경우, HF_TOKEN을 통해 해당 공간에 직접 접근할 수 있으며 할당량도 적용되지 않습니다. 어떤 종류의 프로덕션 작업에든 이 기능을 사용하는 것을 권장합니다.

mcp-hfspace MCP Server

Integrations