Homelab MCP

Servidores MCP para gerenciar infraestrutura de homelab através do Claude Desktop. Monitore contêineres Docker/Podman, modelos de IA Ollama, DNS Pi-hole, redes Unifi e inventário Ansible.

GitHub

Experimente este MCPPatrocinado

Documentação

Servidores MCP Homelab

Servidores Model Context Protocol (MCP) para gerenciar a infraestrutura do seu homelab através do Claude Desktop.

Uma coleção de servidores Model Context Protocol (MCP) para gerenciar e monitorar a infraestrutura do seu homelab através do Claude Desktop.

🔒 Aviso de Segurança

⚠️ IMPORTANTE: Leia SECURITY.md antes de implantar este projeto.

Este projeto interage com infraestrutura crítica (APIs Docker, DNS, dispositivos de rede). Configuração inadequada pode expor seu homelab a riscos de segurança.

Principais Requisitos de Segurança:

NUNCA exponha APIs Docker/Podman à internet - Use regras de firewall para restringir o acesso
Mantenha o arquivo .env seguro - Contém chaves de API e nunca deve ser versionado
Use chaves de API únicas - Gere chaves separadas para cada serviço
Revise a segurança da rede - Garanta segmentação VLAN adequada e regras de firewall

Consulte SECURITY.md para orientações abrangentes de segurança.

📚 Visão Geral da Documentação

Este projeto inclui vários arquivos de documentação para diferentes públicos:

README.md (este arquivo) - Guia de instalação, configuração e uso
MIGRATION_V3.md - Guia de migração para o servidor unificado v2.0
PROJECT_INSTRUCTIONS.md - Copie para as instruções do projeto Claude para contexto de IA
CLAUDE.md - Guia do desenvolvedor para assistentes de IA e colaboradores
SECURITY.md - Políticas de segurança e melhores práticas
CONTRIBUTING.md - Como contribuir com este projeto
CHANGELOG.md - Histórico de versões e alterações

👥 Para Usuários Finais: Siga este README + copie PROJECT_INSTRUCTIONS.md para o Claude 🔄 Migrando da v1.x? Consulte MIGRATION_V3.md para migração do servidor unificado 🤖 Para Assistentes de IA: Leia CLAUDE.md para contexto completo de desenvolvimento 🔧 Para Colaboradores: Comece com CONTRIBUTING.md e CLAUDE.md

📖 Importante: Configure as Instruções do Projeto Claude

Após configurar os servidores MCP, crie suas instruções de projeto personalizadas:

Copie o modelo de exemplo:

# Windows
copy PROJECT_INSTRUCTIONS.example.md PROJECT_INSTRUCTIONS.md

# Linux/Mac
cp PROJECT_INSTRUCTIONS.example.md PROJECT_INSTRUCTIONS.md

Edite o arquivo com os detalhes reais da sua infraestrutura:

PROJECT_INSTRUCTIONS.md (para instruções do projeto Claude Desktop):
- Substitua os endereços IP de exemplo pelos seus endereços de rede reais
- Adicione os nomes de host reais dos seus servidores
- Personalize com seus serviços e configurações específicos
- Mantenha este arquivo privado - contém sua topologia de rede
CLAUDE_CUSTOM.md (para trabalho de desenvolvimento de IA - apenas colaboradores):
- Atualize as URLs do repositório com seu repositório GitHub real
- Adicione as URLs do seu workspace Notion se usar gerenciamento de tarefas
- Personalize as referências de infraestrutura
- Mantenha este arquivo privado - contém suas URLs e configuração específicas
Adicione ao Claude Desktop:
- Abra o Claude Desktop
- Vá para as configurações do seu projeto
- Copie o conteúdo do seu PROJECT_INSTRUCTIONS.md personalizado
- Cole no campo "Instruções do projeto"

O que está incluído:

Capacidades detalhadas dos servidores MCP e padrões de uso
Visão geral da infraestrutura e capacidades de monitoramento
Comandos e ferramentas específicos disponíveis para cada serviço
Orientação de solução de problemas e desenvolvimento

Este README cobre a instalação e configuração básica. As instruções do projeto fornecem ao Claude contexto abrangente de uso.

🎯 Opções de Implantação

Versão 3.0.0 oferece implantação flexível com dois modos e dois métodos:

Modos de Implantação

Escolha como seus servidores MCP são organizados:

1. Servidor Unificado (Recomendado)

Execute todos os servidores MCP em um único processo com ferramentas com namespace. Esta é a abordagem recomendada para novas instalações e obrigatória para implantações Docker.

{
  "mcpServers": {
    "homelab-unified": {
      "command": "python",
      "args": ["C:\\Path\\To\\Homelab-MCP\\homelab_unified_mcp.py"]
    }
  }
}

Vantagens:

✅ Entrada de configuração única
✅ Um processo Python para todos os servidores
✅ Logs mais limpos (sem avisos duplicados)
✅ Todas as ferramentas com namespace (ex.: docker_get_containers, ping_ping_host)
✅ Obrigatório para implantações Docker
✅ Verificações de saúde integradas
✅ Containerização pronta para produção

2. Servidores Individuais (Legado, Totalmente Suportado)

Execute cada servidor MCP como um processo separado. Este modo permanece totalmente suportado para compatibilidade reversa e só está disponível com instalação Python nativa.

{
  "mcpServers": {
    "docker": {
      "command": "python",
      "args": ["C:\\Path\\To\\Homelab-MCP\\docker_mcp_podman.py"]
    },
    "ollama": {
      "command": "python",
      "args": ["C:\\Path\\To\\Homelab-MCP\\ollama_mcp.py"]
    }
  }
}

Vantagens:

✅ Controle granular sobre cada servidor
✅ Pode ativar/desativar servidores individualmente
✅ Nomes de ferramentas originais (ex.: get_docker_containers, ping_host)
✅ Compatível com v1.x

Nota: Os nomes das ferramentas diferem entre os modos. Consulte MIGRATION_V3.md para instruções detalhadas de migração e alterações nos nomes das ferramentas.

Métodos de Implantação

Escolha como instalar e executar os servidores:

1. Contêiner Docker (Recomendado para Produção)

Imagens pré-construídas disponíveis no Docker Hub para implantação imediata. Consulte 🐳 Implantação Docker para instruções completas de configuração.

Início Rápido:

docker pull bjeans/homelab-mcp:latest
docker-compose up -d

Vantagens:

✅ Nenhuma configuração de ambiente Python necessária
✅ Imagens pré-construídas e testadas
✅ Atualizações automáticas com pulls de imagem
✅ Suporte multiplataforma (amd64, arm64)
✅ Configuração simplificada
✅ Containerização de nível de produção

Limitações:

Apenas modo servidor unificado
mcp-registry-inspector não disponível (descontinuado)

2. Instalação Python Nativa (Desenvolvimento e Legado)

Instale as dependências Python diretamente e execute os servidores a partir do código-fonte. Consulte 📦 Instalação para instruções completas de configuração.

Início Rápido:

pip install -r requirements.txt
python homelab_unified_mcp.py

Vantagens:

✅ Acesso total ao código-fonte
✅ Depuração e desenvolvimento fáceis
✅ Suporta modos de servidor unificado e individual
✅ Pode ser executado em qualquer plataforma compatível com Python

Requisitos:

Python 3.10+ com pip
Gerenciamento manual de dependências
Configuração de ambiente via arquivo .env

Guia de Migração: Consulte MIGRATION_V3.md para instruções detalhadas sobre como alternar entre modos ou métodos.

⚡ Framework FastMCP (v3.0.0)

A versão 3.0.0 usa FastMCP: Um framework MCP moderno que simplifica a arquitetura do servidor, adicionando suporte a múltiplos mecanismos de transporte e anotações de ferramentas.

O que é FastMCP?

FastMCP é um framework leve que:

✅ Reduz o código do servidor em 38% (1.754 linhas eliminadas)
✅ Usa padrão simples de decorador (@mcp.tool()) para definições de ferramentas
✅ Inclui anotações abrangentes de ferramentas para dicas comportamentais
✅ Adiciona suporte para transportes HTTP e SSE (além de stdio)
✅ Gera automaticamente esquemas a partir de dicas de tipo Python
✅ Melhora a manutenibilidade do código e facilita a adição de novos servidores

Todas as 39 ferramentas agora incluem anotações MCP (readOnlyHint, idempotentHint, etc.) para ajudar o Claude a tomar decisões informadas sobre o uso das ferramentas.

Opções de Transporte

Os servidores FastMCP podem operar usando diferentes mecanismos de transporte:

1. Entrada/Saída Padrão (stdio) - Padrão

O transporte MCP tradicional usado pelo Claude Desktop. Esta é a opção padrão e recomendada para a maioria dos usuários.

# Run with stdio (default)
python homelab_unified_mcp.py

# Or explicitly specify stdio transport
python homelab_unified_mcp.py --transport stdio

Quando usar:

Integração com Claude Desktop (modo padrão)
Caso de uso mais comum
Nenhuma configuração adicional necessária

2. Transporte HTTP

Execute servidores MCP como serviços HTTP para cenários de implantação remota ou flexível.

# Start server with HTTP transport
python homelab_unified_mcp.py --transport http --host 0.0.0.0 --port 8000

# Test the HTTP endpoint
curl http://localhost:8000/tools

Quando usar:

Implantação de servidores remotamente
Integrações baseadas na web
Cenários com múltiplos clientes
Requisitos de balanceamento de carga

3. Transporte Server-Sent Events (SSE)

Protocolo baseado em fluxo para comunicação bidirecional em tempo real.

# Start server with SSE transport
python homelab_unified_mcp.py --transport sse --host 0.0.0.0 --port 8000

# Connect via SSE client
curl http://localhost:8000/sse

Quando usar:

Aplicações de monitoramento em tempo real
Integrações baseadas em navegador
Arquiteturas orientadas a eventos
Respostas em streaming

Configurando o Claude Desktop com FastMCP

O Claude Desktop continua usando transporte stdio por padrão. Nenhuma alteração de configuração é necessária:

{
  "mcpServers": {
    "homelab-unified": {
      "command": "python",
      "args": ["C:\\Path\\To\\Homelab-MCP\\homelab_unified_mcp.py"]
    }
  }
}

Migração da v2.2.0

Se você está atualizando da v2.2.0:

✅ Sem alterações de quebra - Sua configuração existente continua funcionando sem alterações
✅ Mesma funcionalidade - Todos os 7 servidores e todas as ferramentas permanecem idênticos
✅ Código mais limpo - Refatoração interna produz os mesmos resultados
✅ Novas opções - Transportes HTTP/SSE opcionais disponíveis se necessário

Nenhuma ação necessária - basta atualizar e reiniciar o Claude Desktop.

🚀 Início Rápido

1. Clone o repositório

git clone https://github.com/bjeans/homelab-mcp
cd homelab-mcp

2. Instale as verificações de segurança (recomendado)

# Install pre-push git hook for automatic security validation
python helpers/install_git_hook.py

3. Configure os arquivos de configuração

Variáveis de ambiente:

# Windows
copy .env.example .env

# Linux/Mac
cp .env.example .env

Edite .env com seus valores reais:

# Windows
notepad .env

# Linux/Mac
nano .env

Inventário Ansible (se usado):

# Windows
copy ansible_hosts.example.yml ansible_hosts.yml

# Linux/Mac
cp ansible_hosts.example.yml ansible_hosts.yml

Edite com os detalhes da sua infraestrutura.

Instruções do projeto:

# Windows
copy PROJECT_INSTRUCTIONS.example.md PROJECT_INSTRUCTIONS.md

# Linux/Mac
cp PROJECT_INSTRUCTIONS.example.md PROJECT_INSTRUCTIONS.md

Personalize com sua topologia de rede e servidores.

Personalizações do guia de desenvolvimento de IA (opcional):

# Windows
copy CLAUDE_CUSTOM.example.md CLAUDE_CUSTOM.md

# Linux/Mac
cp CLAUDE_CUSTOM.example.md CLAUDE_CUSTOM.md

Personalize com os nomes reais dos seus servidores e detalhes da infraestrutura. Este arquivo é ignorado pelo git e permite que o Claude entenda sua configuração específica de homelab. Consulte CLAUDE.md para mais informações sobre personalizações locais.

4. Instale as dependências Python

pip install -r requirements.txt

5. Adicione à configuração do Claude Desktop

Localização do arquivo de configuração:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Opção A: Servidor Unificado (Recomendado)

Entrada única para todos os servidores homelab:

{
  "mcpServers": {
    "homelab-unified": {
      "command": "python",
      "args": ["C:\\Path\\To\\Homelab-MCP\\homelab_unified_mcp.py"],
      "env": {
        "ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
      }
    }
  }
}

Nota: O servidor unificado inclui 7 servidores MCP: Ansible, Docker/Podman, Ollama, Pi-hole, Unifi, UPS e Ping. O mcp-registry-inspector descontinuado não está incluído.

Opção B: Servidores Individuais (Legado)

Entrada separada para cada servidor:

{
  "mcpServers": {
    "docker": {
      "command": "python",
      "args": ["C:\\Path\\To\\Homelab-MCP\\docker_mcp_podman.py"],
      "env": {
        "ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
      }
    },
    "ollama": {
      "command": "python",
      "args": ["C:\\Path\\To\\Homelab-MCP\\ollama_mcp.py"],
      "env": {
        "ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
      }
    },
    "pihole": {
      "command": "python",
      "args": ["C:\\Path\\To\\Homelab-MCP\\pihole_mcp.py"],
      "env": {
        "ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
      }
    },
    "unifi": {
      "command": "python",
      "args": ["C:\\Path\\To\\Homelab-MCP\\unifi_mcp_optimized.py"],
      "env": {
        "ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
      }
    },
    "ping": {
      "command": "python",
      "args": ["C:\\Path\\To\\Homelab-MCP\\ping_mcp_server.py"],
      "env": {
        "ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
      }
    },
    "ups-monitor": {
      "command": "python",
      "args": ["C:\\Path\\To\\Homelab-MCP\\ups_mcp_server.py"],
      "env": {
        "ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
      }
    }
  }
}

Nota: Os nomes das ferramentas diferem entre os modos. Consulte MIGRATION_V3.md para detalhes. O mcp-registry-inspector descontinuado foi removido deste exemplo. A integração do servidor MCP Ansible é rastreada em #39.

6. Reinicie o Claude Desktop

7. Adicione as instruções do projeto ao Claude

Copie o conteúdo do seu PROJECT_INSTRUCTIONS.md personalizado
Cole no campo "Instruções do projeto" do seu projeto Claude
Isso dá ao Claude contexto abrangente sobre suas capacidades MCP

🐳 Implantação Docker (Alternativa)

Execute os servidores MCP em contêineres Docker para distribuição mais fácil, isolamento e implantação em produção.

Docker Hub: bjeans/homelab-mcp

Início Rápido com Docker Hub (Mais Fácil)

Imagens pré-construídas são publicadas automaticamente no Docker Hub com suporte multiplataforma (amd64/arm64):

# Pull the latest image
docker pull bjeans/homelab-mcp:latest

# Run with your Ansible inventory
docker run -d \
  --name homelab-mcp \
  --network host \
  -v $(pwd)/ansible_hosts.yml:/config/ansible_hosts.yml:ro \
  bjeans/homelab-mcp:latest

# Or use a specific commit
docker pull bjeans/homelab-mcp:main-17bae01

Disponível no Docker Hub: https://hub.docker.com/r/bjeans/homelab-mcp/tags

Tags atualmente disponíveis:

latest - Última versão estável do branch main (recomendado)
edge - Última build de desenvolvimento do branch main
main-<git-sha> - Builds de commits específicos para rastreabilidade (ex.: main-17bae01)

Tags de versão semântica (disponíveis após o lançamento):

Tags de versão como 2.2.0, 2.2, 2 serão criadas quando o release Git v2.2.0 for publicado
Até lá, use latest para a build estável mais recente

Suporte multiplataforma:

linux/amd64 - Servidores e estações de trabalho x86_64
linux/arm64 - Raspberry Pi, sistemas baseados em ARM

Build a partir do Código-Fonte (Avançado)

Construa a imagem localmente se precisar personalizar:

# Pull the pre-built image from Docker Hub (recommended)
docker pull bjeans/homelab-mcp:latest

# Run with Docker Compose (recommended for production)
docker-compose up -d

# Or run unified server directly
docker run -d \
  --name homelab-mcp \
  --network host \
  -v $(pwd)/ansible_hosts.yml:/config/ansible_hosts.yml:ro \
  bjeans/homelab-mcp:latest

Build a partir do código-fonte (opcional):

# Clone and navigate to repository
git clone https://github.com/bjeans/homelab-mcp
cd homelab-mcp

# Build the image locally
docker build -t homelab-mcp:latest .

Recursos do Docker

2.0.0 Melhorias Docker:

✅ Servidor MCP unificado como entrypoint padrão (todos os 7 servidores em um contêiner)
✅ Detecção automática de modo unificado (sem necessidade de ENABLED_SERVERS)
✅ Verificações de saúde integradas (HEALTHCHECK configurado)
✅ Segurança de usuário não-root (mcpuser UID 1000)
✅ Tratamento adequado de sinais e desligamento limpo
✅ Cache de camadas otimizado para reconstruções mais rápidas
✅ Dependências do sistema incluídas (iputils-ping para suporte multiplataforma)

Métodos de Configuração

Método 1: Inventário Ansible (Recomendado)

# Create your ansible_hosts.yml with infrastructure details
# Then mount as volume:

docker run -d \
  --name homelab-mcp \
  --network host \
  -v $(pwd)/ansible_hosts.yml:/config/ansible_hosts.yml:ro \
  bjeans/homelab-mcp:latest

Método 2: Variáveis de Ambiente (Pronto para Marketplace)

docker run -d \
  --name homelab-mcp \
  --network host \
  -e DOCKER_SERVER1_ENDPOINT=192.168.1.100:2375 \
  -e DOCKER_SERVER1_NAME=Local-Docker \
  -e OLLAMA_SERVER1_ENDPOINT=192.168.1.100:11434 \
  bjeans/homelab-mcp:latest

Modo Legado: Servidores Individuais (Docker)

Para compatibilidade reversa, você ainda pode executar servidores individuais definindo ENABLED_SERVERS:

docker run -d \
  --name homelab-mcp-docker \
  --network host \
  -e ENABLED_SERVERS=docker \
  -v $(pwd)/ansible_hosts.yml:/config/ansible_hosts.yml:ro \
  bjeans/homelab-mcp:latest

Servidores Disponíveis

Modo Unificado (Padrão):

✅ Todos os 7 servidores em um processo: Ansible, Docker, Ping, Ollama, Pi-hole, Unifi, UPS
✅ Ferramentas com namespace (ex.: ansible_get_all_hosts, docker_get_containers, ups_get_ups_status)
✅ Entrada de configuração única
✅ Verificações de saúde integradas

Modo Legado (Defina ENABLED_SERVERS):

✅ ansible - Consultas de inventário Ansible
✅ docker - Gerenciamento de contêineres Docker/Podman
✅ ping - Utilitários de ping de rede
✅ ollama - Gerenciamento de modelos de IA Ollama
✅ pihole - Estatísticas DNS do Pi-hole
✅ unifi - Monitoramento de dispositivos de rede Unifi
✅ ups - Monitoramento de energia UPS/NUT

Configuração Docker

Dois métodos de configuração suportados:

Inventário Ansible (Recomendado) - Montar como volume
Variáveis de Ambiente - Passar via flags -e do Docker

Consulte DOCKER.md para um guia abrangente de implantação Docker, incluindo:

Instruções detalhadas de configuração
Opções de configuração de rede
Melhores práticas de segurança
Integração com Claude Desktop
Solução de problemas comuns

Integração com Claude Desktop

Modo Unificado (Recomendado):

{
  "mcpServers": {
    "homelab-unified": {
      "command": "docker",
      "args": ["exec", "-i", "homelab-mcp", "python", "homelab_unified_mcp.py"]
    }
  }
}

Modo Legado (Servidores Individuais):

{
  "mcpServers": {
    "homelab-docker": {
      "command": "docker",
      "args": ["exec", "-i", "homelab-mcp-docker", "python", "docker_mcp_podman.py"]
    },
    "homelab-ping": {
      "command": "docker",
      "args": ["exec", "-i", "homelab-mcp", "python", "ping_mcp_server.py"]
    }
  }
}

Importante: Use docker exec -i (não -it) para comunicação MCP stdio adequada.

Testando Contêineres Docker

Teste rápido de verificação (usando variáveis de ambiente - pronto para marketplace):

# Test Unified Server
docker run --rm --network host \
    -e DOCKER_SERVER1_ENDPOINT=localhost:2375 \
    -e OLLAMA_SERVER1_ENDPOINT=localhost:11434 \
    bjeans/homelab-mcp:latest

# Test Individual Server (legacy)
docker run --rm --network host \
    -e ENABLED_SERVERS=ping \
    bjeans/homelab-mcp:latest

Teste com Docker Compose:

docker-compose up -d
docker-compose logs -f

Para um guia abrangente de implantação Docker, consulte DOCKER.md.

📦 Servidores MCP Disponíveis

✨ Enums Dinâmicos de Parâmetros de Ferramentas (Novo na v2.1.0)

Quando você configura o inventário Ansible, o Claude Desktop mostrará automaticamente suas opções de infraestrutura em menus suspensos. Chega de adivinhar nomes de hosts ou grupos!

O que é preenchido automaticamente:

Ferramentas de ping - Seus grupos Ansible aparecem em menus suspensos
Ferramentas Docker - Seus hosts Docker/Podman exibidos em menus suspensos
Ferramentas Ollama - Os nomes de host do seu servidor Ollama disponíveis para seleção
Ferramentas UPS - Os nomes de host do seu servidor NUT exibidos em menus suspensos

Como funciona:

Defina ANSIBLE_INVENTORY_PATH no seu arquivo .env
Reinicie o Claude Desktop (obrigatório - os enums são carregados na inicialização)
Ao usar ferramentas, o Claude mostra sua infraestrutura real em menus suspensos em vez de exigir entrada manual

Notas Importantes:

Reinicialização Necessária: Alterações no inventário Ansible exigem reiniciar o Claude Desktop para atualizar as opções do menu suspenso
Desempenho: Os enums são gerados uma vez na inicialização - impacto mínimo mesmo com inventários grandes (100+ hosts)
Degradação Graciosa: Se nenhum inventário Ansible estiver configurado, as ferramentas ainda funcionam - você apenas não verá sugestões no menu suspenso

Exemplo antes/depois:

Antes: "Qual grupo devo pingar?" → O usuário digita manualmente "webservers" (ou adivinha) Depois: "Qual grupo devo pingar?" → O usuário seleciona no menu suspenso: all, docker_hosts, webservers, databases, etc.

Solução de Problemas:

Menus suspensos não aparecem? Verifique se ANSIBLE_INVENTORY_PATH está definido e reinicie o Claude Desktop
Opções erradas aparecendo? Verifique se seu inventário Ansible está atualizado e reinicie o Claude Desktop
Problemas de desempenho? A geração de enums acontece uma vez na inicialização - se estiver lenta, verifique o tamanho do arquivo de inventário e a instalação do Ansible

Inspetor de Registro MCP (⚠️ OBSOLETO)

Aviso de Descontinuação (v2.3.0): Esta ferramenta está obsoleta. O Claude Desktop agora tem acesso nativo ao sistema de arquivos, tornando este servidor MCP desnecessário. Você pode simplesmente pedir ao Claude para ler seus arquivos de servidor MCP ou configuração diretamente.

Substituição: Use o acesso a arquivos integrado do Claude:

"Leia meu arquivo claude_desktop_config.json"
"Mostre-me o código-fonte de docker_mcp_podman.py"
"Liste todos os arquivos .py neste diretório"

Para usuários com configurações existentes: Este servidor continuará funcionando, mas não receberá atualizações. Ele será removido da documentação na v3.0.0. Considere removê-lo do seu claude_desktop_config.json.

Configuração Legada (apenas para referência)

Ferramentas:

get_claude_config - Visualizar configuração MCP do Claude Desktop
list_mcp_servers - Listar todos os servidores MCP registrados
list_mcp_directory - Navegar pelo diretório de desenvolvimento MCP
read_mcp_file - Ler código-fonte do servidor MCP
write_mcp_file - Escrever/atualizar arquivos do servidor MCP
search_mcp_files - Pesquisar arquivos por nome

Configuração:

MCP_DIRECTORY=/path/to/your/Homelab-MCP
CLAUDE_CONFIG_PATH=/path/to/claude_desktop_config.json  # Optional

Gerenciador de Contêineres Docker/Podman

Gerencie contêineres Docker e Podman em vários hosts.

🔒 Aviso de Segurança: As APIs Docker/Podman normalmente usam HTTP não criptografado sem autenticação. Consulte SECURITY.md para a configuração de firewall necessária.

Ferramentas:

Modo de servidor individual:

get_docker_containers - Obter contêineres em um host específico
get_all_containers - Obter todos os contêineres em todos os hosts
get_container_stats - Obter estatísticas de CPU e memória
check_container - Verificar se um contêiner específico está em execução
find_containers_by_label - Encontrar contêineres por rótulo
get_container_labels - Obter todos os rótulos de um contêiner

Modo de servidor unificado (com namespace):

docker_get_containers - Obter contêineres em um host específico
docker_get_all_containers - Obter todos os contêineres em todos os hosts
docker_get_container_stats - Obter estatísticas de CPU e memória
docker_check_container - Verificar se um contêiner específico está em execução
docker_find_containers_by_label - Encontrar contêineres por rótulo
docker_get_container_labels - Obter todos os rótulos de um contêiner

Opções de Configuração:

Opção 1: Usando Inventário Ansible (Recomendado)

ANSIBLE_INVENTORY_PATH=/path/to/ansible_hosts.yml

# Ansible inventory group names (default: docker_hosts, podman_hosts)
# Change these if you use different group names in your ansible_hosts.yml
DOCKER_ANSIBLE_GROUP=docker_hosts
PODMAN_ANSIBLE_GROUP=podman_hosts

Opção 2: Usando Variáveis de Ambiente

DOCKER_SERVER1_ENDPOINT=192.168.1.100:2375
DOCKER_SERVER2_ENDPOINT=192.168.1.101:2375
PODMAN_SERVER1_ENDPOINT=192.168.1.102:8080

Gerenciador de Modelos de IA Ollama

Monitore e gerencie instâncias de modelos de IA Ollama em todo o seu homelab, além de verificar seu proxy LiteLLM para acesso unificado à API.

O que está Incluído

Monitoramento Ollama:

Acompanhe várias instâncias Ollama em diferentes hosts
Visualize modelos disponíveis e seus tamanhos
Verifique a saúde e disponibilidade das instâncias

Integração com Proxy LiteLLM:

O LiteLLM fornece uma API unificada compatível com OpenAI em todas as suas instâncias Ollama
Permite balanceamento de carga e failover entre vários servidores Ollama
Permite usar bibliotecas de cliente OpenAI com seus modelos locais
O servidor MCP pode verificar se seu proxy LiteLLM está online e respondendo

Por que usar LiteLLM?

Balanceamento de Carga: Distribui automaticamente as solicitações entre várias instâncias Ollama
Failover: Se um servidor Ollama estiver inativo, as solicitações são roteadas para servidores saudáveis
Compatibilidade com OpenAI: Use qualquer SDK/biblioteca OpenAI com seus modelos locais
Acesso Centralizado: Endpoint único (ex.: http://192.0.2.10:4000) para todos os modelos
Rastreamento de Uso: Monitore quais modelos estão sendo mais usados

Ferramentas:

get_ollama_status - Verificar status de todas as instâncias Ollama e contagens de modelos
get_ollama_models - Obter lista detalhada de modelos para um host específico
get_litellm_status - Verificar se o proxy LiteLLM está online e respondendo

Opções de Configuração:

Opção 1: Usando Inventário Ansible (Recomendado)

ANSIBLE_INVENTORY_PATH=/path/to/ansible_hosts.yml
OLLAMA_PORT=11434  # Default Ollama port

# Ansible inventory group name (default: ollama_servers)
# Change this if you use a different group name in your ansible_hosts.yml
OLLAMA_INVENTORY_GROUP=ollama_servers

# LiteLLM Configuration
LITELLM_HOST=192.168.1.100  # Host running LiteLLM proxy
LITELLM_PORT=4000           # LiteLLM proxy port (default: 4000)

Opção 2: Usando Variáveis de Ambiente

# Ollama Instances
OLLAMA_SERVER1=192.168.1.100
OLLAMA_SERVER2=192.168.1.101
OLLAMA_WORKSTATION=192.168.1.150

# LiteLLM Proxy
LITELLM_HOST=192.168.1.100
LITELLM_PORT=4000

Configurando LiteLLM (Opcional):

Se você quiser usar LiteLLM para acesso unificado às suas instâncias Ollama:

Instale o LiteLLM em um dos seus servidores:
```
pip install litellm[proxy]
```

Crie a configuração (litellm_config.yaml):

model_list:
  - model_name: llama3.2
    litellm_params:
      model: ollama/llama3.2
      api_base: http://server1:11434
  - model_name: llama3.2
    litellm_params:
      model: ollama/llama3.2
      api_base: http://server2:11434

router_settings:
  routing_strategy: usage-based-routing

Inicie o proxy LiteLLM:

litellm --config litellm_config.yaml --port 4000

Use a ferramenta MCP para verificar se está em execução:
- No Claude: "Verifique o status do meu proxy LiteLLM"

Exemplo de Uso:

"Quais instâncias Ollama estou executando?"
"Mostre-me todos os modelos no meu Dell-Server"
"Meu proxy LiteLLM está online?"
"Quantos modelos estão disponíveis em todos os servidores?"

Gerenciador DNS Pi-hole

Monitore estatísticas e status DNS do Pi-hole.

🔒 Nota de Segurança: Armazene as chaves de API do Pi-hole com segurança no arquivo .env. Gere chaves únicas por instância.

Ferramentas:

get_pihole_stats - Obter estatísticas DNS de todas as instâncias Pi-hole
get_pihole_status - Verificar quais instâncias Pi-hole estão online

Opções de Configuração:

Opção 1: Usando Inventário Ansible (Recomendado)

ANSIBLE_INVENTORY_PATH=/path/to/ansible_hosts.yml

# Ansible inventory group name (default: PiHole)
# Change this if you use a different group name in your ansible_hosts.yml
PIHOLE_ANSIBLE_GROUP=PiHole

# API keys still required in .env:
PIHOLE_API_KEY_SERVER1=your-api-key-here
PIHOLE_API_KEY_SERVER2=your-api-key-here

Opção 2: Usando Variáveis de Ambiente

PIHOLE_API_KEY_SERVER1=your-api-key
PIHOLE_API_KEY_SERVER2=your-api-key
PIHOLE_SERVER1_HOST=pihole1.local
PIHOLE_SERVER1_PORT=80
PIHOLE_SERVER2_HOST=pihole2.local
PIHOLE_SERVER2_PORT=8053

Obtendo Chaves de API do Pi-hole:

Interface Web: Configurações → API → Mostrar Token da API
Ou gere um novo: pihole -a -p no servidor Pi-hole

Monitor de Rede Unifi

Monitore a infraestrutura de rede Unifi e clientes com cache para desempenho.

🔒 Nota de Segurança: Use uma chave de API dedicada com as permissões mínimas necessárias.

Ferramentas:

get_network_devices - Obter todos os dispositivos de rede (switches, APs, gateways)
get_network_clients - Obter todos os clientes de rede ativos
get_network_summary - Obter visão geral da rede
refresh_network_data - Forçar atualização do controlador (ignora o cache)

Configuração:

UNIFI_API_KEY=your-unifi-api-key
UNIFI_HOST=192.168.1.1

Nota: Os dados são armazenados em cache por 5 minutos para melhorar o desempenho. Use refresh_network_data para forçar a atualização.

Inspetor de Inventário Ansible

Consulte informações do inventário Ansible (somente leitura). Disponível nos modos unificado e autônomo.

Ferramentas do Modo Unificado (com prefixo ansible_):

ansible_get_all_hosts - Obter todos os hosts do inventário
ansible_get_all_groups - Obter todos os grupos
ansible_get_host_details - Obter informações detalhadas do host
ansible_get_group_details - Obter informações detalhadas do grupo
ansible_get_hosts_by_group - Obter hosts em grupo específico
ansible_search_hosts - Pesquisar hosts por padrão ou variável
ansible_get_inventory_summary - Visão geral de alto nível do inventário
ansible_reload_inventory - Recarregar inventário do disco

Ferramentas do Modo Autônomo (sem prefixo):

get_all_hosts - Obter todos os hosts do inventário
get_all_groups - Obter todos os grupos
get_host_details - Obter informações detalhadas do host
get_group_details - Obter informações detalhadas do grupo
get_hosts_by_group - Obter hosts em grupo específico
search_hosts - Pesquisar hosts por padrão ou variável
get_inventory_summary - Visão geral de alto nível do inventário
reload_inventory - Recarregar inventário do disco

Configuração:

ANSIBLE_INVENTORY_PATH=/path/to/ansible_hosts.yml

Implantação:

✅ Disponível no modo de servidor unificado
✅ Disponível em implantações Docker
✅ Disponível no modo autônomo: python ansible_mcp_server.py

Monitor de Conectividade de Rede Ping

Teste a conectividade de rede e a disponibilidade de hosts usando ping ICMP em toda a sua infraestrutura.

Por que usar isso?

Verificações rápidas de saúde durante interrupções ou após eventos de energia
Verifique quais hosts estão acessíveis antes de consultar MCPs específicos de serviços
Ferramenta simples de solução de problemas para identificar problemas de rede
Teste de conectividade de linha de base para sua infraestrutura

Ferramentas:

ping_host - Pingar um único host pelo nome (resolvido do inventário Ansible)
ping_group - Pingar todos os hosts de um grupo Ansible simultaneamente
ping_all - Pingar todos os hosts da infraestrutura simultaneamente
list_groups - Listar grupos Ansible disponíveis para operações de ping

Recursos:

✅ Suporte multiplataforma - Funciona em Windows, Linux e macOS
✅ Integração com Ansible - Resolve automaticamente hostnames/IPs do inventário
✅ Pings simultâneos - Testa vários hosts ao mesmo tempo para resultados mais rápidos
✅ Estatísticas detalhadas - RTT mínimo/médio/máximo, porcentagem de perda de pacotes
✅ Personalizável - Configure timeout e quantidade de pacotes
✅ Sem dependências - Usa o comando ping do sistema (sem bibliotecas extras)

Configuração:

ANSIBLE_INVENTORY_PATH=/path/to/ansible_hosts.yml
# No additional API keys required!

Exemplo de uso:

"Ping server1.example.local"
"Verificar conectividade com todos os servidores Pi-hole"
"Ping todos os hosts Ubuntu_Server"
"Testar conectividade com toda a infraestrutura"
"Quais grupos posso pingar?"

Quando usar:

Após quedas de energia - Identifique rapidamente quais hosts voltaram online
Antes de verificações de serviço - Verifique se o host está acessível antes de checar serviços específicos
Solução de problemas de rede - Isole problemas de conectividade de problemas de serviço
Monitoramento de saúde - Verificações regulares para garantir a disponibilidade da infraestrutura

Monitoramento de UPS (Network UPS Tools)

Monitore dispositivos UPS (Fonte de Alimentação Ininterrupta) em toda a sua infraestrutura usando o protocolo Network UPS Tools (NUT).

Por que usar isso?

Visibilidade em tempo real do status da infraestrutura de energia
Alertas proativos antes do esgotamento da bateria durante quedas de energia
Monitore vários dispositivos UPS em diferentes hosts
Acompanhe a saúde da bateria e estimativas de tempo de execução
Essencial para o planejamento de infraestrutura crítica

Ferramentas:

get_ups_status - Verifica o status de todos os dispositivos UPS em todos os servidores NUT
get_ups_details - Obtém informações detalhadas de um dispositivo UPS específico
get_battery_runtime - Obtém estimativas de tempo de execução da bateria para todos os dispositivos UPS
get_power_events - Verifica eventos recentes de energia (em bateria, bateria fraca)
list_ups_devices - Lista todos os dispositivos UPS configurados no inventário
reload_inventory - Recarrega o inventário do Ansible após alterações

Recursos:

✅ Suporte ao protocolo NUT - Usa o protocolo padrão Network UPS Tools (porta 3493)
✅ Integração com Ansible - Descobre automaticamente UPS do inventário
✅ Múltiplas UPS por host - Suporte para servidores com vários dispositivos UPS
✅ Monitoramento de bateria - Acompanhe nível de carga, tempo restante, porcentagem de carga
✅ Detecção de eventos de energia - Identifique quando a UPS alterna para bateria ou bateria fraca
✅ Multiplataforma - Funciona com qualquer UPS compatível com NUT (TrippLite, APC, CyberPower, etc.)
✅ Autenticação flexível - Autenticação opcional por usuário/senha

Configuração:

Opção 1: Usando o Inventário do Ansible (Recomendado)

ANSIBLE_INVENTORY_PATH=/path/to/ansible_hosts.yml

# Default NUT port (optional, defaults to 3493)
NUT_PORT=3493

# NUT authentication (optional - only if your NUT server requires it)
NUT_USERNAME=monuser
NUT_PASSWORD=secret

Exemplo de inventário Ansible:

nut_servers:
  hosts:
    dell-server.example.local:
      ansible_host: 192.168.1.100
      nut_port: 3493
      ups_devices:
        - name: tripplite
          description: "TrippLite SMART1500LCDXL"

Opção 2: Usando Variáveis de Ambiente

NUT_PORT=3493
NUT_USERNAME=monuser
NUT_PASSWORD=secret

Pré-requisitos:

Instale o NUT nos servidores com dispositivos UPS:

# Debian/Ubuntu
sudo apt install nut nut-client nut-server

# RHEL/Rocky/CentOS
sudo dnf install nut nut-client

Configure o daemon NUT (/etc/nut/ups.conf):

[tripplite]
    driver = usbhid-ups
    port = auto
    desc = "TrippLite SMART1500LCDXL"

Habilite o monitoramento de rede (/etc/nut/upsd.conf):
```
LISTEN 0.0.0.0 3493
```

Configure o acesso (/etc/nut/upsd.users):

[monuser]
    password = secret
    upsmon master

Inicie os serviços NUT:

sudo systemctl enable nut-server nut-client
sudo systemctl start nut-server nut-client

Exemplo de uso:

"Qual é o status de todos os meus dispositivos UPS?"
"Mostre o tempo de bateria restante para a UPS do servidor Dell"
"Verifique se há eventos de energia"
"Obtenha informações detalhadas sobre a UPS TrippLite"
"Liste todos os dispositivos UPS configurados"

Quando usar:

Após oscilações de energia - Verifique se os dispositivos UPS lidaram corretamente com o evento
Antes de manutenções - Verifique os níveis de bateria e o tempo estimado de execução
Monitoramento regular - Acompanhe a saúde da UPS e a condição da bateria
Planejamento de capacidade - Entenda por quanto tempo os sistemas podem funcionar com bateria

Códigos de status comuns de UPS:

OL - Online (operação normal, energia CA presente)
OB - Em bateria (queda de energia, operando com bateria)
LB - Bateria fraca (bateria criticamente baixa, desligamento iminente)
CHRG - Carregando (bateria em carregamento)
RB - Substituir bateria (bateria precisa ser substituída)

🔒 Segurança

Verificações de Segurança Automatizadas

Este projeto inclui validação de segurança automatizada para evitar a exposição acidental de dados sensíveis:

Instale o hook git pre-push (recomendado):

# From project root
python helpers/install_git_hook.py

O que ele faz:

Executa automaticamente helpers/pre_publish_check.py antes de cada git push
Bloqueia pushes que contenham possíveis segredos ou dados sensíveis
Protege contra o commit acidental de chaves de API, senhas ou informações pessoais

Verificação de segurança manual:

# Run security validation manually
python helpers/pre_publish_check.py

Ignorar verificação de segurança (use com extrema cautela):

# Only when absolutely necessary
git push --no-verify

Práticas Críticas de Segurança

Arquivos de Configuração:

✅ FAÇA use .env.example como modelo
✅ FAÇA mantenha as permissões do arquivo .env restritivas (chmod 600 no Linux/Mac)
❌ NUNCA envie .env para o controle de versão
❌ NUNCA envie ansible_hosts.yml com infraestrutura real
❌ NUNCA envie PROJECT_INSTRUCTIONS.md com topologia de rede real

Segurança de API:

✅ FAÇA use chaves de API exclusivas para cada serviço
✅ FAÇA rotacione as chaves de API regularmente (recomendado a cada 90 dias)
✅ FAÇA use chaves fortes, geradas aleatoriamente (32+ caracteres)
❌ NUNCA exponha APIs Docker/Podman à internet
❌ NUNCA reutilize chaves de API entre ambientes

Segurança de Rede:

✅ FAÇA use regras de firewall para restringir o acesso à API
✅ FAÇA implemente segmentação VLAN
✅ FAÇA habilite TLS/HTTPS quando possível
❌ NUNCA exponha interfaces de gerenciamento publicamente

Para orientações detalhadas de segurança, consulte SECURITY.md

📋 Requisitos

Requisitos do Sistema

Python: 3.10 ou superior
Claude Desktop: Versão mais recente recomendada
Acesso à rede: Conectividade com os serviços do homelab

Dependências Python

Instale via requirements.txt:

pip install -r requirements.txt

Dependências principais:

mcp - SDK do Model Context Protocol
aiohttp - Cliente HTTP assíncrono
pyyaml - Análise YAML para inventário Ansible

Requisitos de Serviço

Docker/Podman: API habilitada nos hosts monitorados
Pi-hole: v6+ com API habilitada
Unifi Controller: Acesso à API habilitado
Ollama: Instâncias em execução com API acessível
NUT (Network UPS Tools): Instalado e configurado nos hosts com dispositivos UPS
Ansible: Arquivo de inventário (opcional, mas recomendado)

💻 Compatibilidade

Plataformas Testadas

Desenvolvido e testado em:

SO: Windows 11
Claude Desktop: Versão 0.13.64
Python: Versão 3.13.8

Notas de Compatibilidade entre Plataformas

Windows: Totalmente testado e suportado ✅ macOS: Deve funcionar, mas não testado ⚠️ Linux: Deve funcionar, mas não testado ⚠️

Diferenças conhecidas entre plataformas:

Caminhos de arquivo na documentação seguem o padrão Windows
Os separadores de caminho podem precisar de ajustes para sistemas Unix
As permissões de arquivo .env devem ser definidas no Unix (chmod 600 .env)

Contribuições para outras plataformas são bem-vindas!

🛠️ Desenvolvimento

📖 Contribuindo pela primeira vez? Leia CLAUDE.md para orientações completas de desenvolvimento, incluindo padrões de arquitetura, requisitos de segurança e fluxos de trabalho para assistentes de IA.

Começando

Instale o hook de segurança git (obrigatório para contribuidores):
```
python helpers/install_git_hook.py
```

Configure o ambiente de desenvolvimento:

pip install -r requirements.txt
cp .env.example .env
# Edit .env with your test values

Testando Servidores MCP Localmente

Antes de enviar um PR, teste suas alterações no servidor MCP localmente usando a ferramenta MCP Inspector.

Início rápido:

# MCP Inspector is an optional Node.js tool for interactive testing
# Option 1: Use npx (no installation needed - recommended)
npx @modelcontextprotocol/inspector uv --directory . run <server>_mcp.py

# Option 2: Install globally first (one-time setup)
npm install -g @modelcontextprotocol/inspector
# Then run: mcp-inspector uv --directory . run <server>_mcp.py

Isso abre um depurador baseado na web em http://localhost:5173 onde você pode:

Ver todas as ferramentas disponíveis para o servidor MCP
Testar cada ferramenta com argumentos de exemplo
Verificar se as respostas estão formatadas corretamente
Depurar problemas antes de enviar PRs

Para instruções detalhadas de teste, consulte a seção Testando Servidores MCP Localmente em CONTRIBUTING.md.

Scripts Auxiliares

O diretório helpers/ contém scripts utilitários para desenvolvimento e implantação:

install_git_hook.py - Instala o hook git pre-push para verificações de segurança automáticas
pre_publish_check.py - Script de validação de segurança (executado automaticamente via hook git)

Uso:

# Install security git hook
python helpers/install_git_hook.py

# Run security check manually  
python helpers/pre_publish_check.py

Estrutura do Projeto

Homelab-MCP/
├── MCP Servers (7 production servers)
│   ├── ansible_mcp_server.py      # Ansible inventory queries (integration in progress)
│   ├── docker_mcp_podman.py       # Docker/Podman container monitoring
│   ├── ollama_mcp.py              # Ollama AI model management
│   ├── pihole_mcp.py              # Pi-hole DNS monitoring
│   ├── ping_mcp_server.py         # Network connectivity testing
│   ├── unifi_mcp_optimized.py     # Unifi network device monitoring
│   └── ups_mcp_server.py          # UPS/NUT monitoring
│
├── Unified Server & Core Modules
│   ├── homelab_unified_mcp.py     # Combines all servers (Docker entrypoint)
│   ├── mcp_config_loader.py       # Secure environment variable loading
│   ├── mcp_error_handler.py       # Centralized error handling
│   └── ansible_config_manager.py  # Ansible inventory + enum generation
│
├── Utilities & Deprecated Tools
│   ├── unifi_exporter.py          # Unifi data export utility
│   └── mcp_registry_inspector.py  # MCP file management (⚠️ DEPRECATED v2.3.0)
│
├── Configuration & Examples
│   ├── .env.example               # Configuration template (gitignored)
│   ├── ansible_hosts.example.yml  # Ansible inventory example (gitignored)
│   ├── PROJECT_INSTRUCTIONS.example.md # AI assistant guide template
│   └── CLAUDE_CUSTOM.example.md   # Local customization template (gitignored)
│
├── Documentation
│   ├── README.md                  # This file - user documentation
│   ├── CLAUDE.md                  # AI assistant development guide
│   ├── SECURITY.md                # Security guidelines
│   ├── CONTRIBUTING.md            # Contribution guide
│   ├── CHANGELOG.md               # Version history
│   ├── MIGRATION_V3.md               # Version migration guide
│   ├── CONTEXT_AWARE_SECURITY.md  # Security scanning docs
│   ├── CI_CD_CHECKS.md            # CI/CD automation docs
│   └── LICENSE                    # MIT License
│
├── Docker Deployment
│   ├── Dockerfile                 # Container build configuration
│   ├── docker-compose.yml         # Container orchestration (uses bjeans/homelab-mcp:latest)
│   └── docker-entrypoint.sh       # Container startup script
│
├── Development Tools
│   ├── helpers/
│   │   ├── install_git_hook.py    # Git pre-push hook installer
│   │   ├── pre_publish_check.py   # Security validation
│   │   ├── run_checks.py          # CI/CD check runner
│   │   └── requirements-dev.txt   # Development dependencies
│   ├── requirements.txt           # Production Python dependencies
│   └── .gitignore                 # Git ignore rules

Adicionando um Novo Servidor MCP

Crie o arquivo do servidor

#!/usr/bin/env python3
"""
My Service MCP Server
Description of what it does
"""
import asyncio
from mcp.server import Server
# ... implement tools ...

Adicione a configuração ao .env.example

# My Service Configuration
MY_SERVICE_HOST=192.168.1.100
MY_SERVICE_API_KEY=your-api-key

Atualize a documentação
- Adicione os detalhes do servidor a este README
- Atualize PROJECT_INSTRUCTIONS.example.md
- Atualize CLAUDE.md se estiver adicionando novos padrões ou capacidades
- Adicione notas de segurança quando aplicável
Teste minuciosamente
- Teste com infraestrutura real
- Verifique o tratamento de erros
- Verifique vazamentos de dados sensíveis
- Revise as implicações de segurança

Variáveis de Ambiente

Todos os servidores MCP suportam dois métodos de configuração:

1. Variáveis de Ambiente (arquivo .env)

Pares simples de chave=valor
Carregadas automaticamente por cada servidor MCP
Boas para configurações simples ou testes

2. Inventário Ansible (recomendado para produção)

Definição centralizada da infraestrutura
Suporta agrupamentos complexos de hosts
Melhor para ambientes com vários hosts
Defina ANSIBLE_INVENTORY_PATH em .env

Padrões de Codificação

Sintaxe e recursos Python 3.10+
Async/await para todas as operações de I/O
Anotações de tipo onde for benéfico
Tratamento de erros para operações de rede
Registro de logs em stderr para depuração
Segurança: Valide entradas, sanitize saídas

Checklist de Testes

Antes de confirmar alterações:

Hook de segurança git instalado (python helpers/install_git_hook.py)
Verificação de segurança manual aprovada (python helpers/pre_publish_check.py)
Sem dados sensíveis no código ou nos commits
Variáveis de ambiente para toda a configuração
Tratamento de erros para falhas de rede
Logs não expõem segredos
Documentação atualizada
Implicações de segurança revisadas
.gitignore atualizado se necessário

🐛 Solução de Problemas

Servidores MCP Não Aparecem no Claude

Verifique a configuração do Claude Desktop:

# Windows
type %APPDATA%\Claude\claude_desktop_config.json

# Mac/Linux
cat ~/.config/Claude/claude_desktop_config.json

Verifique se o caminho do Python está correto na configuração
Reinicie o Claude Desktop completamente
Verifique os logs - Os servidores MCP registram logs em stderr

Erros de Conexão

API Docker/Podman:

# Test connectivity
curl http://your-host:2375/containers/json

# Check firewall
netstat -an | grep 2375

API Pi-hole:

# Test API key
curl "http://your-pihole/api/stats/summary?sid=YOUR_API_KEY"

Ollama:

# Test Ollama endpoint
curl http://your-host:11434/api/tags

Entendendo Mensagens de Erro

Formato da Mensagem de Erro (v2.2.0+):

Todos os servidores MCP agora fornecem mensagens de erro detalhadas e acionáveis neste formato:

✗ [Service] [Error Type] (HTTP Status)

[Specific problem description]

Host: [hostname:port]

→ [Actionable remediation steps]

Technical details: [error details] (timestamp)

Tipos Comuns de Erro:

1. Falha de Autenticação (401)

Exemplo:

✗ Pi-hole Authentication Failed (401)

Invalid API key for pi-hole-1

Host: 192.168.1.5:80

→ Verify PIHOLE_API_KEY_PI_HOLE_1 in .env matches your Pi-hole admin password.
→ You can find/reset this in Pi-hole Settings > API.

Como Corrigir:

Verifique seu arquivo .env para a variável correta da chave de API
Confirme se a chave de API corresponde ao painel administrativo do serviço
Para Pi-hole: Configurações > API > Mostrar token da API
Para Unifi: Configurações > Administradores > API > Gerar chave

2. Falha de Conexão

Exemplo:

✗ Unifi Connection Failed

Unable to connect to unifi-controller:443

Host: unifi-controller:443

→ Ensure Unifi controller is running and accessible at unifi-controller:443.
→ Test connectivity: nc -zv unifi-controller 443
→ Check firewall: sudo iptables -L | grep 443

Como Corrigir:

Verifique se o serviço está em execução: systemctl status [service-name]
Teste a conectividade de rede com nc ou telnet
Verifique se as regras de firewall permitem acesso à porta
Confirme se o hostname/IP está correto na sua configuração

3. Erros de Timeout

Exemplo:

✗ Ollama Timeout

Connection to ollama-1:11434 timed out (after 5s)

Host: ollama-1:11434

→ The service is not responding. Check if Ollama is running and not overloaded.
→ Check service status and logs for performance issues.

Como Corrigir:

Verifique se o serviço está em execução: systemctl status ollama
Procure problemas de desempenho nos logs do serviço
Verifique a latência da rede: ping [hostname]
Considere aumentar os valores de timeout se o serviço for legitimamente lento

4. Credenciais Inválidas/Expiradas (403)

Exemplo:

✗ Service Authorization Failed (403)

Valid credentials but insufficient permissions

→ Ensure the API key/account has the required permissions for this operation.

Como Corrigir:

Verifique as permissões da conta no painel administrativo do serviço
Garanta que a chave de API tenha direitos de administrador/acesso total
Regere a chave de API se as permissões foram alteradas recentemente

5. Erros do Unifi Exporter

Antes (v2.1.0):

Error: Exporter failed with code 1

Depois (v2.2.0):

✗ Unifi Authentication Failed

Invalid Unifi API key for unifi-controller

Host: unifi-controller

→ Verify UNIFI_API_KEY in .env matches the API key from Unifi Settings > Admins > API.
→ Ensure the key has not expired.

Technical details: 401 Unauthorized (at 2025-11-20T10:30:45Z)

Como Corrigir:

Faça login no controlador Unifi
Navegue até Configurações > Administradores > API
Verifique ou regere a chave de API
Atualize UNIFI_API_KEY no arquivo .env
Reinicie o Claude Desktop para recarregar a configuração

6. Serviço Indisponível (503)

Como Corrigir:

Verifique se o serviço está em execução
Procure por erros de inicialização do serviço nos logs
Verifique se todas as dependências estão disponíveis
Considere reiniciar o serviço

Dicas de Depuração

Ative o Registro Detalhado:

Todos os erros são registrados em stderr com contexto completo. Verifique os logs do Claude Desktop:

Windows: %APPDATA%\Claude\logs\
Mac: ~/Library/Logs/Claude/
Linux: ~/.config/Claude/logs/

Teste os Endpoints da API Diretamente:

Use curl ou httpie para testar endpoints da API fora do MCP:

# Pi-hole
curl "http://pi-hole:80/api/stats/summary?sid=YOUR_API_KEY"

# Docker
curl http://docker-host:2375/containers/json

# Unifi (requires SSL and API key)
curl -k -H "X-API-KEY: YOUR_KEY" https://unifi:443/api/stat/sta

# Ollama
curl http://ollama:11434/api/tags

# NUT (Network UPS Tools)
telnet nut-server 3493
> LIST UPS

Verifique a Configuração:

# Verify .env file exists and is readable
ls -la .env

# Check for syntax errors in .env
cat .env | grep -v '^#' | grep -v '^$'

# Verify Ansible inventory
ansible-inventory -i ansible_hosts.yml --list

Erros de Importação

Se você obtiver erros de importação do Python:

# Reinstall dependencies
pip install --upgrade -r requirements.txt

# Verify MCP installation
pip show mcp

Erros de Permissão

No Linux/Mac:

# Fix .env permissions
chmod 600 .env

# Make scripts executable
chmod +x *.py

📚 Recursos Adicionais

Protocolo MCP

Projetos Relacionados

📄 Licença

Licença MIT - Veja o arquivo LICENSE para detalhes

🤝 Contribuindo

Contribuições são bem-vindas! Consulte CONTRIBUTING.md para obter diretrizes detalhadas.

Para Assistentes de IA e Desenvolvedores

📖 Leia CLAUDE.md primeiro - Este arquivo contém:

Arquitetura completa do projeto e padrões de desenvolvimento
Requisitos de segurança e armadilhas comuns a evitar
Fluxos de trabalho específicos para adicionar recursos e corrigir bugs
Orientação específica para assistentes de IA ao trabalhar com este código

Início Rápido para Contribuidores

Instale o git hook de segurança (python helpers/install_git_hook.py)
Revise as diretrizes de segurança em SECURITY.md
Sem dados sensíveis em commits (o hook bloqueará automaticamente)
Toda a configuração usa variáveis de ambiente ou Ansible
Atualize a documentação para quaisquer alterações
Teste minuciosamente com infraestrutura real

Processo de Pull Request

Faça um fork do repositório
Crie um branch de funcionalidade (git checkout -b feature/amazing-feature)
Faça suas alterações
Teste com sua configuração de homelab
Atualize o README e outros documentos conforme necessário
Faça commit com mensagens claras (git commit -m 'Add amazing feature')
Envie para o seu fork (git push origin feature/amazing-feature)
Abra um Pull Request

Critérios de Revisão de Código

Práticas de segurança seguidas
Sem credenciais ou IPs codificados
Tratamento de erros adequado
Código segue os padrões existentes
Documentação clara e completa
Alterações testadas

🙏 Agradecimentos

Anthropic pelo Claude e MCP
A comunidade homelab pela inspiração
Contribuidores e testadores

📞 Suporte

Issues: GitHub Issues
Discussões: GitHub Discussions
Segurança: Veja SECURITY.md para reportar vulnerabilidades

Lembre-se: Este projeto lida com infraestrutura crítica. Sempre priorize a segurança e teste as alterações em um ambiente seguro primeiro!