MCP Hub

Один MCP-сервер, который дает вашему ИИ-ассистенту ключи от всей вашей домашней лаборатории.

MCP Hub — это один сервер Model Context Protocol, который работает на одной машине в вашей сети и распределяет команды оттуда: SSH на каждый хост вашего парка, контейнеры Proxmox, Docker, Synology DSM, туннели и DNS Cloudflare, рабочие процессы n8n, Notion, ваше хранилище паролей. Вместо того чтобы запускать дюжину MCP-серверов и подключать каждый к вашему клиенту, вы запускаете один и направляете на него своего ассистента.

"Почему Jellyfin недоступен?" — и ассистент проверяет контейнер, читает журнал, замечает, что туннельный вход устарел, исправляет его и сообщает, что сделал.

⚠️ Прочтите SECURITY.md перед развертыванием. MCP Hub предоставляет LLM root-доступ к оболочке по всему вашему парку. В этом и заключается его суть, и это действительно опасно. Настройки по умолчанию безопасны (127.0.0.1, только чтение); опасность начинается, когда вы их меняете.

Демонстрация устранения неполадок

Репозиторий содержит очищенную запись Asciinema полного сеанса устранения неполадок, основанного на наблюдении: неработающая конечная точка, диагностика systemd, точный план изменений, явное подтверждение, перезапуск и финальные проверки работоспособности. В ней используется пример инвентаризации и не содержится данных частной инфраструктуры.

asciinema play docs/troubleshooting.cast

См. запись напрямую, если Asciinema не установлен; формат cast — это JSON с разделителями строк, который остается читаемым.

Related MCP server: homelab-mcp

Содержание

• Возможности

• Быстрый старт

• Развертывание

• Локальное тестирование

• Аварийная диагностика

• Конфигурация

• Справочник инструментов

• Безопасность

• Версионирование

• Участие в разработке

Возможности

• 111 инструментов, одна конечная точка, один конфигурационный файл.

• Управление через конфигурацию. Ваша сеть живет в hosts.yaml и .env. Никакая информация о вашей инфраструктуре не вшита в код.

• Мультиплексированный SSH. Постоянные управляющие сокеты, поэтому команды для всего парка выполняются за миллисекунды, а не за каждый TCP-рукопожатие.

• Опциональные интеграции. Каждая интеграция отключена по умолчанию и включается одним флагом. Запускайте его как чистый SSH-инструмент для парка, если это все, что вам нужно.

• Подключаемые секреты. Чтение учетных данных из окружения или из хранилища Bitwarden/Vaultwarden через bw serve.

• Аутентификация по Bearer-токену поверх непредсказуемого пути конечной точки.

• Глобальный режим только для чтения, включен по умолчанию: один флаг отключает все 43 изменяющих инструмента, применяется централизованно, а не по одному инструменту.

• Автоматическое редактирование секретов при чтении файлов и выводе команд.

• Фоновые задания с опросом, журналами и постоянным хранилищем состояний SQLite.

Быстрый старт

Требуется Python 3.11+ и хост Linux с SSH-доступом к машинам, которыми вы хотите управлять.

git clone https://github.com/wnx82/mcp-hub.git
cd mcp-hub

python3 -m venv .venv && . .venv/bin/activate
pip install -e .

cp .env.example .env                  # then edit — see below
cp hosts.example.yaml hosts.yaml      # then edit: your fleet
chmod 600 .env hosts.yaml

python server.py

Как минимум, установите эти два параметра в .env:

MCP_SECRET_PATH=/$(openssl rand -hex 16)   # unguessable endpoint path
MCP_AUTH_TOKEN=$(openssl rand -hex 32)     # bearer token — the real auth

Затем сервер слушает на http://127.0.0.1:8000<MCP_SECRET_PATH>, с MCP_READ_ONLY=true. Направьте ваш MCP-клиент на этот URL и отправьте Authorization: Bearer <MCP_AUTH_TOKEN>. Запросы без токена получают 401; запросы к любому другому пути получают 404.

Для локального MCP-клиента, который хочет stdio вместо HTTP, запустите тот же хаб с:

mcp-hub --transport stdio

или установите MCP_TRANSPORT=stdio в окружении перед запуском.

Для развертывания через systemd, sudo ./deploy/install.sh создает выделенного пользователя mcphub и SSH-ключ, генерирует оба секрета в /etc/default/mcp-hub и устанавливает юнит. Он идемпотентен и никогда не перезаписывает существующую конфигурацию. См. deploy/.

Для полной настройки Claude Code, безопасной обработки токенов, проверки соединения, первого запроса только для чтения и текущего ограничения Claude Desktop см. Подключение MCP Hub к Claude.

Если вы хотите, чтобы ваш ассистент понимал вашу частную топологию, роли хостов, окна изменений и правила работы MCP, не фиксируя эти данные, начните с PROJECT_INSTRUCTIONS.example.md и храните ваш настроенный PROJECT_INSTRUCTIONS.md только локально.

Развертывание

MCP Hub поддерживает три режима выполнения:

Пакет Python и прямое выполнение используют текущий checkout и его virtualenv. Они не создают служебную учетную запись, SSH-ключ, файл окружения или политику перезапуска. Установщик systemd предоставляет эти операционные части, сохраняет локальную конфигурацию при повторном запуске и устанавливает Rescue вне virtualenv хаба.

Образы контейнеров пока не являются официальной целью развертывания. Хабу нужен сетевой доступ, SSH-идентификация, постоянный state.db и доступ к его локальной инвентаризации; операторы, упаковывающие его в контейнер, должны сами сохранить эти свойства.

См. docs/docker-packaging.md для текущих требований и того, что должен гарантировать официальный образ, прежде чем его можно будет рекомендовать.

Локальное тестирование

Для чек-листа, ориентированного на контрибьюторов, охватывающего линтинг, модульные тесты, регистрацию инструментов, сгенерированную документацию, дымовые тесты установщика и ручной запуск только для чтения, см. docs/testing-local.md.

Для сводки миграции MCP 2026-07-28, матрицы совместимости и процедуры отката см. docs/migration/mcp-2026-07-28-guide.md.

Перед открытием PR или публикацией ветки вы также можете запустить локальные проверки готовности к релизу:

python3 scripts/check_repo_hygiene.py
python3 scripts/check_tool_annotations.py
python3 scripts/check_security_readiness.py

Чтобы автоматически подключить проверку готовности безопасности к Git при отправке:

./scripts/install_pre_push_hook.sh

Архитектура

server.py остается корнем композиции MCP-сервера, в то время как код предметной области постепенно перемещается в tools/. Построение SSH-команд, пути Cloudflare и извлечение ответов, метаданные протокола DSM, инвентаризация и построители плейбуков уже изолированы. tools/registry.py назначает извлеченные инструменты домену; этот домен включается в каждую сводку аудита. Новая логика протокола должна находиться в своем доменном модуле и не должна импортировать server.py.

Будущие интеграции приоритизированы в docs/integration-evaluation.md, включая их область наименьших привилегий и шлюзы продвижения.

Аварийная диагностика

mcp-hub-rescue — это локальный CLI только для чтения, предназначенный для работы, когда основной сервер не может импортировать или его virtualenv сломан. Установщик systemd копирует его в /opt/mcp-hub-rescue и запускает с системным Python, вне процесса MCP Hub и virtualenv.

sudo mcp-hub-rescue doctor
sudo mcp-hub-rescue status
sudo mcp-hub-rescue health
sudo mcp-hub-rescue logs --lines 50
sudo mcp-hub-rescue validate-config

Результаты — структурированный JSON. Rescue никогда не импортирует server.py, tools/*, MCP или опциональную интеграцию, и эта граница обеспечивается CI. Текущие команды только наблюдают и диагностируют; операции перезапуска, восстановления и отката будут добавлены отдельно с подтверждением и защитой последнего известного рабочего состояния.

Конфигурация

Все файлы игнорируются Git — у каждого есть отслеживаемый шаблон .example:

Запись хоста минимальна по замыслу:

hosts:
  nas:
    hostname: nas.example.lan
    user: admin
    role: storage
    tags: [nas, backup]
    mac: "aa:bb:cc:dd:ee:01"   # optional, enables wake_host()

Теги — это то, как вы обращаетесь к группам: fleet_exec(tag="backup", command="df -h"). Для готовой к копированию инвентаризации из двух хостов начните с docs/examples/hosts.minimal.yaml. Более крупный hosts.example.yaml демонстрирует все поддерживаемые опции хоста.

Сопоставьте его с docs/examples/topology.guarded.yaml, чтобы сопоставить гостей Proxmox, записать ловушки устаревших адресов и выявить инфраструктуру, которую нельзя менять без необходимости. Записи _do_not_touch — это операционный контекст для ассистента, а не принудительная граница контроля доступа; используйте профили токенов и ограничения хостов для технического принуждения.

Добавьте docs/examples/endpoints.minimal.yaml для мониторинга постоянно включенных и периодических HTTP-сервисов. Вызывайте endpoints_health() для обычного набора или endpoints_health(include_intermittent=true) для включения сервисов, которые могут быть обычно выключены. Ответы от 200 до 399 считаются здоровыми; перенаправления не отслеживаются.

Полные значения по умолчанию, лимиты, настройки интеграции и примечания по обработке секретов находятся в справочнике переменных окружения.

Сопоставьте эти отслеживаемые примеры с частным, неотслеживаемым PROJECT_INSTRUCTIONS.md, чтобы ваш ассистент видел оговорки по топологии, окна обслуживания, соглашения об именах и указания "не трогать", которые не должны находиться в репозитории.

Справочник инструментов

Каждый инструмент возвращает одну и ту же обертку верхнего уровня:

{
  "ok": true,
  "data": {},
  "error": null,
  "duration_ms": 12,
  "host": "example",
  "request_id": "4d52b1f69b974b7784bf65dd",
  "tool": "system_info"
}

data содержит полезную нагрузку, специфичную для инструмента. Отказы безопасности и контролируемые исключения используют ту же форму с ok: false, что делает цепочки вызовов и корреляцию аудита предсказуемыми.

Центральная обертка инструмента также ограничивает размер запроса, количество вызовов на токен, одновременные вызовы на цель, повторные сбои цели и частоту изменений. Значения по умолчанию задокументированы в .env.example; отказы по лимитам используют ту же обертку ответа и аудиторский след, что и любой другой вызов.

Полная сгенерированная документация по инструментам раскрывает каждую группу в таблицу с точной сигнатурой каждого инструмента и описанием для модели. CI проверяет её на соответствие зарегистрированным функциям.

Направленная диагностика всегда останавливается после наблюдения. Она возвращает доказательства, оценку и предлагаемые следующие шаги с correction_applied: false; check_backup_chain — это сигнал свежести и хранилища, а не подтверждение, что восстановление будет успешным.

Безопасность

MCP Hub — это служба удалённого выполнения кода по своей конструкции. Перед тем как открыть доступ:

• Оставьте привязку по умолчанию 127.0.0.1 или поместите её за туннель с политиками доступа.

• Установите MCP_AUTH_TOKEN — секретный путь URL — это не аутентификация, а обфускация.

• Оставьте MCP_READ_ONLY=true, пока вы не доверяете тому, что ваша модель с ним делает.

• Оставьте включёнными настройки защиты ресурсов по умолчанию, затем настраивайте их на основе наблюдаемого трафика аудита, а не отключайте.

• Выделите ей отдельный SSH-ключ и минимальный hosts.yaml.

Полная модель угроз, руководство по усилению защиты и отчётности об уязвимостях: SECURITY.md.

Для локального чек-листа перед публикацией и опционального Git-хука, который перехватывает распространённые ошибки утечки секретов до отправки, смотрите scripts/check_security_readiness.py и scripts/install_pre_push_hook.sh.

Версионирование

SemVer. До версии 1.0 критические изменения повышают минорную версию — поэтому читайте заметки Changed и Removed перед обновлением на одну версию. _version.py — единственный источник истины; работающий сервер сообщает её через mcp-hub --version, в рукопожатии MCP и в mcp_health.

Каждый релиз задокументирован в CHANGELOG.md, причём изменения, связанные с безопасностью, выделены в отдельный раздел.

Вклад

Приветствуются сообщения об ошибках и запросы на слияние — особенно отчёты об ошибках, новые интеграции и исправления документации. Смотрите CONTRIBUTING.md.

Лицензия

MIT © wnx82