Homelab MCP Server

👁 CI
👁 Python 3.12+
👁 License: MIT

Управление инфраструктурой домашней лаборатории с помощью ИИ через протокол Model Context Protocol

🏆 Заявка на хакатон TestSprite Season 2

Ветка: TestSprite_Hackathon | Итоговый процент прохождения: 10/10 (100%)

Что я создал

homelab_mcp — это сервер MCP (Model Context Protocol); он не использует REST. TestSprite тестирует REST API. Основной задачей этой заявки было преодоление разрыва между протоколами.

Решение: Обертка FastAPI, которая предоставляет все 56 инструментов MCP в виде полноценных REST-эндпоинтов, дополненных документированным контрактом HTTP-ошибок, чтобы TestSprite мог использовать весь функционал инструментов без знания протокола MCP.

TestSprite Agent → FastAPI wrapper (port 8080) → homelab_mcp tools → Infrastructure

Проектирование контракта ошибок

Вместо возврата стандартных 500-х ошибок, обертка реализует трехуровневый контракт HTTP-ошибок:

Дизайн 424 Failed Dependency — самая интересная часть. Инструменты, взаимодействующие с реальной инфраструктурой (SSH-хосты, Proxmox API, TrueNAS), выполняют TCP-проверку перед вызовом обработчика. Если цель недоступна, обертка возвращает 424 со структурированной полезной нагрузкой — status, host, port, protocol и подсказкой по исправлению requires — даже не обращаясь к обработчику. Никакого частичного выполнения, никакой утечки учетных данных на недоступные хосты.

Как только этот контракт был задокументирован в спецификации Swagger, TestSprite автоматически сгенерировал негативные тест-кейсы для всех трех типов ошибок.

Результаты тестирования — Пять запусков

Исправления, выполненные TestSprite

Запуск набора тестов TestSprite

# Clone the hackathon branch
git clone -b TestSprite_Hackathon https://github.com/washyu/homelab_mcp.git
cd homelab_mcp

# Install dependencies
uv sync

# Start the FastAPI wrapper (no auth mode for testing)
uv run python run_server.py --openapi --port 8080 --no-auth

# TestSprite test cases are in testsprite_tests/
# Run via the TestSprite agent pointed at http://localhost:8080

Извлеченные уроки

1. Серверам MCP нужен REST-фасад для обычных инструментов тестирования API

2. Ваша спецификация Swagger — это ваш план тестирования — документируйте контракты ошибок, и TestSprite сгенерирует тесты для них

3. Точность code_summary.yaml имеет значение — неправильные имена полей создают неправильные тесты

4. Добавьте защитные барьеры CLAUDE.md перед тем, как подпускать Claude Code к TestSprite — без них он будет автономно зацикливаться на исправлении и перезапуске, расходуя кредиты

5. Исключите testsprite_tests/ из линтера и форматтера — относитесь к ним как к vendor/

6. Фиксируйте или копируйте отчеты после каждого запуска — сводка перезаписывается каждый раз

7. Режимы с аутентификацией и без требуют отдельных запусков — невозможно охватить оба в одной сессии TestSprite

Полная статья: shaunjackson.space

Python MCP-сервер, который позволяет ИИ-ассистентам управлять, развертывать и отслеживать инфраструктуру домашней лаборатории. Инструменты охватывают обнаружение по SSH, управление виртуальными машинами, установку сервисов, отображение топологии сети, операции Proxmox и управление учетными данными.

Ключевые особенности

• SSH-обнаружение -- Сбор исчерпывающей информации об оборудовании и программном обеспечении с любой системы

• Установка сервисов -- Развертывание Jellyfin, Pi-hole, Ollama, Home Assistant и других из шаблонов

• Интеграция с Proxmox -- Полный доступ к API плюс обнаружение скриптов сообщества

• Жизненный цикл ВМ/контейнеров -- Развертывание, управление и удаление рабочих нагрузок Docker и LXD

• Картографирование сети -- Обнаружение устройств, анализ топологии и отслеживание изменений

• Terraform и Ansible -- Развертывания с управлением состоянием, обнаружением отклонений и плейбуками

• Управление учетными данными -- Зарегистрируйте серверы один раз, подключайтесь без повторного ввода учетных данных

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

# Install from PyPI (recommended — no clone needed)
uvx homelab-mcp

# Or clone and run from source
git clone https://github.com/washyu/homelab_mcp.git
cd homelab_mcp
uv sync && uv run python run_server.py

Полное руководство (переменные окружения, настройка MCP-клиента, первый вызов инструмента) см. в Руководстве по установке.

Документация

Как это работает

1. Настройка -- Сервер генерирует пару SSH-ключей при первом запуске (~/.ssh/mcp_admin_rsa)

2. Подключение хоста -- Используйте setup_mcp_admin для создания управляемого пользователя в целевой системе

3. Проверка -- Используйте verify_mcp_admin для подтверждения доступа по SSH без пароля

4. Управление -- Обнаруживайте оборудование, устанавливайте сервисы, управляйте ВМ и составляйте карту сети

Сервер обменивается данными через stdio с использованием протокола MCP. Подключите его к любому MCP-совместимому клиенту (Claude Desktop и т.д.) и взаимодействуйте с помощью естественного языка.

Управление учетными данными

Сохраните учетные данные SSH и Proxmox один раз, чтобы сервер автоматически подставлял их при каждом подключении:

# Store an SSH credential
homelab-mcp credentials add 192.168.1.10 admin

# Store an SSH key-based credential (stores the key file path in the keyring, not the key)
homelab-mcp credentials add 192.168.1.10 admin --key-path ~/.ssh/id_ed25519

# Store a Proxmox API credential
homelab-mcp credentials add 192.168.1.200 root@pam --type proxmox

# Update an existing credential — `add` is upsert; re-running replaces the stored entry
homelab-mcp credentials add 192.168.1.10 admin

# List stored credentials
homelab-mcp credentials list
homelab-mcp credentials list --type proxmox

# Remove a credential
homelab-mcp credentials remove 192.168.1.10

CLI предоставляет полный CRUD для учетных данных: add (создание/обновление — upsert), list (чтение), remove (удаление). Отдельной подкоманды update нет — повторный запуск add заменяет как секрет в связке ключей, так и тип аутентификации в реестре.

Учетные данные хранятся в системной связке ключей (libsecret в Linux, Keychain в macOS). Когда системная связка ключей недоступна (на безголовых серверах), учетные данные считываются из переменных окружения.

См. Справочник CLI учетных данных для получения полной документации.

Настройка MCP-клиента

Из PyPI (uvx) — рекомендуется:

{
 "mcpServers": {
 "homelab": {
 "command": "uvx",
 "args": ["homelab-mcp"]
 }
 }
}

Из исходного кода:

{
 "mcpServers": {
 "homelab": {
 "command": "uv",
 "args": ["run", "python", "run_server.py"],
 "cwd": "/path/to/homelab_mcp"
 }
 }
}

Разработка

# Install with dev dependencies
uv sync --group dev

# Run tests (unit only, no Docker required)
uv run pytest tests/ -m "not integration"

# Code quality
uv run ruff check src/ tests/
uv run mypy src/

См. DEPLOYMENT.md для получения подробной информации о развертывании в продакшене.

Структура проекта

src/homelab_mcp/
 server.py # MCP server with JSON-RPC protocol
 tool_schemas/ # Tool definitions (8 schema files)
 tool_annotations.py # MCP annotation hints per tool
 ssh_tools.py # SSH discovery and hardware detection
 service_installer.py # Service installation framework
 infrastructure_crud.py # Infrastructure lifecycle management
 vm_operations.py # VM/container operations
 sitemap.py # Network topology mapping
 database.py # SQLite device tracking
 error_handling.py # Centralized error handling
 credential_store.py # OS keyring credential storage
 log_filter.py # Credential redaction for log output
 prompt_registry.py # MCP prompts registry
 resource_readers.py # MCP resource read handlers
 service_templates/ # YAML service definitions
testsprite_tests/ # TestSprite generated test suite (hackathon)
tests/ # Unit and integration tests
docs/ # Full documentation

Благодарности

Интеграция скриптов сообщества Proxmox реализована на базе community-scripts/ProxmoxVE (лицензия MIT).

Вклад в проект

1. Сделайте форк репозитория

2. Создайте ветку для новой функции

3. Напишите тесты для нового функционала

4. Убедитесь, что все тесты проходят

5. Отправьте pull request

Лицензия

Лицензия MIT — подробности см. в файле LICENSE.

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers

Tools

• analyze_network_topologyB
• bulk_discover_and_mapA
• check_ansible_serviceB
• check_service_requirementsA
• clone_proxmox_vmB
• control_vmB
• create_infrastructure_backupC
• create_proxmox_lxcB