Официальный MCP‑сервер Hugging Face

Добро пожаловать на официальный MCP‑сервер Hugging Face 🤗. Подключите вашу модель большого языка (LLM) к Hugging Face Hub и к тысячам Gradio AI‑приложений.

Установка MCP‑сервера

Следуйте инструкциям ниже, чтобы начать работу:

Установить в Claude Desktop или claude.ai

Нажмите здесь, чтобы добавить коннектор Hugging Face к вашей учетной записи.

Или перейдите к Настройки коннекторов Claude и добавьте "Hugging Face" из галереи.

Установить в Claude Code

Введите приведённую ниже команду, чтобы установить в Claude Code:

claude mcp add hf-mcp-server -t http https://huggingface.co/mcp?login

Затем запустите claude и следуйте инструкциям для завершения аутентификации.

claude mcp add hf-mcp-server \
  -t http https://huggingface.co/mcp \
  -H "Authorization: Bearer <YOUR_HF_TOKEN>"

Установить в Gemini CLI

Введите приведённую ниже команду, чтобы установить в Gemini CLI:

gemini mcp add -t http huggingface https://huggingface.co/mcp?login

Затем запустите gemini и следуйте инструкциям для завершения аутентификации.

Установить в VSCode

Нажмите [здесь] чтобы добавить коннектор Hugging Face непосредственно в VSCode. Либо установите из галереи по адресу Галерея MCP для VSCode:

Если вы предпочитаете настроить вручную или использовать auth token, добавьте следующий сниппет в конфигурацию вашего mcp.json:

"huggingface": {
    "url": "https://huggingface.co/mcp",
    "headers": {
        "Authorization": "Bearer <YOUR_HF_TOKEN>"
    }
}

Установить в Cursor

Нажмите здесь для установки Hugging Face MCP Server напрямую в Cursor.

Если вы предпочитаете настроку вручную или используете токен авторизации, воспользуйтесь сниппетом ниже:

"huggingface": {
    "url": "https://huggingface.co/mcp",
    "headers": {
        "Authorization": "Bearer <YOUR_HF_TOKEN>"
    }
}

После установки перейдите к Настройки MCP и настройте ваши Tools и Spaces.

Подсказка

Добавьте ?no_image_content=true к URL, чтобы исключить блоки ImageContent на Gradio Servers.

Быстрое руководство (пакеты репозитория)

В этом репозитории есть:

(/mcp) Реализации MCP для Hub API и конечных точек поиска, предназначенные для интеграции с MCP‑серверы.
(/app) MCP‑сервер и веб‑приложение для развёртывания конечных точек.

MCP Server

Поддерживаются следующие транспорты:

STDIO
StreamableHTTP в Stateless JSON Mode (StreamableHTTPJson)

Веб‑приложение и HTTP‑транспорты по умолчанию запускаются на порту 3000.

Сервис StreamableHTTP доступен по адресу /mcp. Хотя это не строго требуется по спецификации, это распространённая практика.

Веб‑приложение сообщает статус сервера и метрики методов MCP. Выбор инструментов разрешается независимо для каждого запроса на основе опциональной пользовательской конфигурации Hugging Face API и параметров запроса bouquet/mix.

Запуск локально

Вы можете запустить MCP Server локально с помощью npx или docker.

npx @llmindset/hf-mcp-server       # Запуск в режиме STDIO
npx @llmindset/hf-mcp-server-http  # Запуск в Stateless Streamable HTTP JSON режиме

Чтобы запустить с использованием docker:

docker pull ghcr.io/evalstate/hf-mcp-server:latest
docker run --rm -p 3000:3000 ghcr.io/evalstate/hf-mcp-server:latest

Все приведённые выше команды запускают управление Web-интерфейсом по адресу http://localhost:3000/. Стримимый HTTP‑сервер доступен по адресу http://localhost:3000/mcp. Ознакомьтесь с [Environment Variables](#Environment Variables) для настроек. По умолчанию Docker использует режим Streamable HTTP (JSON RPC).

Разработка

Этот проект использует pnpm для сборки и разработки. Corepack обеспечивает единый версию pnpm (10.12.3) для всех.

# Установка зависимостей
pnpm install

# Сборка всех пакетов
pnpm build

Команды сборки

"pnpm run clean" — очистить артефакты сборки
"pnpm run build" — собрать пакеты
"pnpm run start" — запустить приложение mcp server
"pnpm run buildrun" — очистить, собрать и запустить
"pnpm run dev" — параллельно наблюдать за mcp и запускать dev‑сервер с HMR

Сборка Docker‑образа

Соберите образ:

docker build -t hf-mcp-server .

Запуск с настройками по умолчанию (Streaming HTTP JSON Mode), панель управления доступна на порту 3000.

HTTP‑клиенты должны отправлять токен Hugging Face в заголовке Authorization: Bearer:

docker run --rm -p 3000:3000 hf-mcp-server

Запуск MCP Server в STDIO:

docker run -i --rm -e TRANSPORT=stdio -p 3000:3000 -e DEFAULT_HF_TOKEN=hf_xxx hf-mcp-server

TRANSPORT может принимать значения stdio или streamableHttpJson (значение по умолчанию).

Эндпойнты транспорта

Разные типы транспорта используют следующие эндпойнты:

Stateless Streamable HTTP JSON: /mcp
STDIO: использует stdin/stdout напрямую, HTTP‑эндпойнт отсутствует

Переменные окружения

Сервер поддерживает следующие переменные окружения:

TRANSPORT: тип транспорта, который следует использовать (stdio или streamableHttpJson)
DEFAULT_HF_TOKEN: дефолтный токен для локальных deployments через STDIO. HTTP‑транспорты не используют его как запасной вариант для запросов без заголовка Authorization: Bearer.
Если запускается транспорт stdio, HF_TOKEN используется, если DEFAULT_HF_TOKEN не задан.
MCP_ALLOWED_HOSTS: дополнительный перечисляемый через запятую список разрешённых хостов для MCP и маршрутов API. Локальные хосты localhost,127.0.0.1,::1 всегда разрешены. Используйте точные имена хостов или ведущие подстановочные записи вида *.example.com.
HF_API_TIMEOUT: тайм-аут запросов к Hugging Face API в миллисекундах (по умолчанию 12500 мс / 12,5 секунд)
USER_CONFIG_API: необязательный URL для настроек Hugging Face MCP на каждого пользователя. При отсутствии используются неизменяемые встроенные значения.
ALLOW_INTERNAL_ADDRESS_HOSTS: необязательный список хостов через запятую, разрешающий внутренние/зарезервированные DNS‑разрешения для доверенных доменов во время исходящих проверок (поддерживает точные хосты и *.wildcards, например: huggingface.co,*.hf.space).
MCP_STRICT_COMPLIANCE: установить True для отклонённых GET 405 в JSON Mode (по умолчанию выводит приветственную страницу).
DISABLE_TOOLS: необязательный список имён инструментов через запятую для скрытия из tools/list и отказа в вызове, например hub_repo_search,hf_fs. Отклонённые вызовы остаются видимыми как ошибки в статистике вызовов инструментов MCP.
PROXY_TOOLS_CSV: необязательный CSV, который задаёт источники прокси‑инструментов Streamable HTTP (см. ниже).
PROXY_TOKEN: необязательный токен, используемый только для аутентификации при старте при обнаружении схем PROXY_TOOLS_CSV.
GRADIO_SKIP_INITIALIZE: если значение равно true, вызовы Gradio MCP пропускают handshake initialize и выполняют напрямую tools/call.
HF_SKILLS_DIR: локальный каталог, содержащий заранее созданный снимок навыков SEP-2640: skills.json содержит uri каждого навыка, полный frontmatter и для каждого файла {uri,digest} манифест ресурсов, вместе с расширенными директориями навыков. При HTTP‑транспортах сервер проверяет каждый исходный SHA‑256 digest и удостоверяется в реальном frontmatter файла SKILL.md перед атомарным сохранением всех файлов в память. Снимки имеют TTL свежести три часа; устаревшие запросы продолжают использовать последний действительный снимок, пока не будет загружено и проверено новое обновление, и сбой обновления сохраняет этот проверенный снимок с пятиминутной задержкой повторной попытки. HTTP‑сервер реализует skills/list, skills/get, resources/read и необязательный resources/directory/read, а также объявляет io.modelcontextprotocol/skills с directoryRead: true только если доступен валидный снимок. Навыки не expose-ятся через долговременный STDIO‑транспорт. По умолчанию путь равен /mnt/hf-skills/distribution/latest, предназначен для тома Hugging Face Space, смонтированного из hf://buckets/huggingface/skills.

Чтобы expose общий каталог навыков Hugging Face из Space, смонтируйте bucket и удерживайте HF_SKILLS_DIR, указывающим на его последний дистрибутив:

/ -v hf://buckets/huggingface/skills:/mnt/hf-skills:ro hf spaces volumes set <org>/<space> -v hf://buckets/huggingface/skills:/mnt/hf-skills:ro hf spaces variables add <org>/<space> -e HF_SKILLS_DIR=/mnt/hf-skills/distribution/latest

Проксирующие инструменты (Streamable HTTP через CSV)

Вы можете загрузить определения прокси‑инструментов при запуске, установив PROXY_TOOLS_CSV на HTTPS URL или на локальный путь к файлу.

Если эти прокси‑серверы требуют аутентификации, задайте PROXY_TOKEN. Пользовательские, дефолтные и логирующие токены не используются для обнаружения схем прокси при старте.

Сервер извлекает каждый MCP‑эндпойнт один раз при запуске, выполняет initialize + tools/list (тайм-аут 10 секунд) и регистрирует возвращённые инструменты.

Если источник не работает или возвращает пустой набор инструментов, он пропускается (запуск не падает).

Формат CSV

tool_name,url,response_type
papers,https://evalstate-hf-papers.hf.space/mcp,SSE
news,https://example.com/mcp,JSON

tool_name: локальное имя инструмента для одного источника; идентификатор прокси‑источника, когда upstream предоставляет несколько инструментов.
url: конечная точка Streamable HTTP MCP.
response_type: поле совместимости; принимаются SSE и JSON. Пр(proxy)-запросы могут по‑прежнему использовать ответы Streamable HTTP upstream, тогда как этот сервер всегда возвращает прямые JSON‑RPC‑ответы своим клиентам.

Именование инструментов

Именование инструментов зависит от того, сколько инструментов возвращает upstream MCP:

Один инструмент на upstream: экспонируемое имя инструмента — это первый столбец CSV.
Несколько инструментов на upstream: экспонируемыми именами инструментов являются имена инструментов upstream.

Если экспонируемое имя proxy‑инструмента конфликтует с уже зарегистрированным инструментом, proxy‑инструмент пропускается и регистрируется предупреждение.

Эти имена инструментов можно использовать в bouquets или mixes по мере необходимости.

Используйте bouquet=proxy или mix=proxy, чтобы включить все proxy‑инструменты, загруженные из PROXY_TOOLS_CSV (в дополнение к базовым встроенным инструментам).