Homelab MCP Server

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

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 a Proxmox API credential
homelab-mcp credentials add 192.168.1.200 root@pam --type proxmox

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

# Remove a credential
homelab-mcp credentials remove 192.168.1.10

Учетные данные хранятся в связке ключей ОС (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
tests/                   # Unit and integration tests
docs/                    # Full documentation

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

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

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

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

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

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

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

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

Лицензия

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