Homelab MCP Server

Gerencie e monitore sistemas de homelab via SSH.

Documentação

Servidor MCP Homelab

Gerenciamento de Infraestrutura Homelab com IA via Protocolo de Contexto de Modelo

Um servidor MCP em Python que permite que assistentes de IA gerenciem, implantem e monitorem infraestrutura homelab. As ferramentas abrangem descoberta SSH, gerenciamento de VMs, instalação de serviços, mapeamento de topologia de rede, operações Proxmox e gerenciamento de credenciais.

Principais Recursos

Descoberta SSH — Coleta informações abrangentes de hardware e software de qualquer sistema
Instalação de Serviços — Implanta Jellyfin, Pi-hole, Ollama, Home Assistant e outros a partir de modelos
Integração Proxmox — Acesso completo à API, além de descoberta de scripts da comunidade
Ciclo de Vida de VMs/Contêineres — Implanta, controla e remove cargas de trabalho Docker e LXD
Mapeamento de Rede — Descobre dispositivos, analisa topologia e rastreia mudanças
Terraform e Ansible — Implantações gerenciadas por estado com detecção de desvios e playbooks
Gerenciamento de Credenciais — Registre servidores uma vez, conecte-se sem reinserir credenciais

Início Rápido

# 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

Para o passo a passo completo (variáveis de ambiente, configuração do cliente MCP, primeira chamada de ferramenta), consulte o Guia de Configuração.

Documentação

Guia	Descrição
Guia de Configuração	Do zero à primeira chamada de ferramenta
Referência de Ferramentas	Todas as ferramentas com argumentos e exemplos
Configuração	Variáveis de ambiente e opções de CLI
Configuração do Claude Desktop	Guia de integração com Claude Desktop
Serviço HTTP	Modo REST/OpenAPI, endpoints e contrato de erros

Como Funciona

Configuração — O servidor gera um par de chaves SSH na primeira execução (~/.ssh/mcp_admin_rsa)
Integre um host — Use setup_mcp_admin para criar um usuário gerenciado no sistema de destino
Verifique — Use verify_mcp_admin para confirmar acesso SSH sem senha
Gerencie — Descubra hardware, instale serviços, controle VMs e mapeie sua rede

O servidor se comunica via stdio usando o protocolo MCP. Conecte-o a qualquer cliente compatível com MCP (Claude Desktop, etc.) e interaja por meio de linguagem natural.

Gerenciamento de Credenciais

Armazene credenciais SSH e Proxmox uma única vez para que o servidor as injete automaticamente em cada conexão:

# 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

A CLI oferece CRUD completo sobre credenciais: add (criar/atualizar — upsert), list (ler), remove (excluir). Não há subcomando update separado — executar add novamente substitui tanto o segredo do chaveiro quanto o tipo de autenticação da entrada do registro.

As credenciais são armazenadas no chaveiro do sistema operacional (libsecret no Linux, Keychain no macOS). Quando o chaveiro do sistema operacional não está disponível (servidores headless), as credenciais são armazenadas em variáveis de ambiente.

Consulte a referência da CLI de Credenciais para documentação completa.

Configuração do Cliente MCP

A partir do PyPI (uvx) — recomendado:

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

A partir do clone da fonte:

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

Desenvolvimento

# 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/

Consulte DEPLOYMENT.md para detalhes de implantação em produção.

Estrutura do Projeto

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

Agradecimentos

Integração de scripts da comunidade Proxmox alimentada por community-scripts/ProxmoxVE (Licença MIT).

Contribuindo

Faça um fork do repositório
Crie um branch de funcionalidade
Escreva testes para novas funcionalidades
Garanta que todos os testes passem
Envie um pull request

Licença

Licença MIT — consulte o arquivo LICENSE para detalhes.