Pi-hole

pihole-mcp

Um servidor MCP de nível de produção para Pi-hole v6.

76+ ferramentas | 9 prompts | 5 recursos | Multi-instância + sincronização | Binário único em Go | Download de 6,4 MB (slim: 3,8 MB)

Dá aos assistentes de IA controle total sobre sua instância do Pi-hole — bloqueio de DNS, gerenciamento de domínios, análise de consultas, estatísticas, dispositivos de rede, DHCP e administração do sistema. Compatível com a API REST do Pi-hole v6.

Início Rápido

A maioria dos clientes MCP usa o mesmo formato de configuração. Adicione isto à configuração do seu cliente:

{
  "mcpServers": {
    "pihole": {
      "command": "pihole-mcp",
      "env": {
        "PIHOLE_URL": "http://192.168.1.2",
        "PIHOLE_PASSWORD": "your-password"
      }
    }
  }
}

Em seguida, instale o binário por um dos métodos abaixo.

Instalação

Registro MCP

O pihole-mcp está listado no Registro MCP oficial como:

io.github.hexamatic/pihole-mcp

Clientes que suportam instalação via registro podem adicioná-lo por esse nome e serão solicitados a fornecer PIHOLE_URL e PIHOLE_PASSWORD. A listagem aponta para a imagem ghcr.io, portanto o cliente precisa de um Docker funcional.

Homebrew

brew install hexamatic/tap/pihole-mcp

Instala tanto no macOS quanto no Linux (Homebrew no Linux). No macOS, o cask remove o atributo de quarentena durante a instalação, então o binário é executado sem o prompt do Gatekeeper.

Scoop (Windows)

scoop bucket add hexamatic https://github.com/hexamatic/scoop-bucket
scoop install pihole-mcp

Instalação via Go

go install github.com/hexamatic/pihole-mcp/cmd/pihole-mcp@latest

Docker

docker pull ghcr.io/hexamatic/pihole-mcp:latest

Pacotes Linux

Pacotes .deb e .rpm para distribuições baseadas em Debian (Ubuntu, Raspberry Pi OS) e baseadas em RPM (Fedora, RHEL) estão disponíveis na página de Releases.

# Debian / Ubuntu / Raspberry Pi OS
sudo dpkg -i pihole-mcp_X.Y.Z_linux_amd64.deb

# Fedora / RHEL / CentOS
sudo rpm -i pihole-mcp_X.Y.Z_linux_amd64.rpm

Download do Binário

Binários pré-compilados para Linux, macOS e Windows (amd64 e arm64) estão disponíveis na página de Releases.

Os releases são verificados por checksum, assinados com cosign sem chave e incluem SBOMs SPDX e proveniência de build SLSA — veja SECURITY.md para os comandos de verificação.

Configuração

Senhas de aplicativo são recomendadas para automação — elas ignoram o 2FA TOTP e podem ser revogadas de forma independente.

PIHOLE_RATE_LIMIT e PIHOLE_ALLOWED_ORIGINS se aplicam apenas aos transportes http e sse; stdio é um canal de processo único e usuário único por definição e não é limitado.

Múltiplas instâncias

Para gerenciar mais de um Pi-hole, configure instâncias numeradas em vez de PIHOLE_URL/PIHOLE_PASSWORD:

{
  "mcpServers": {
    "pihole": {
      "command": "pihole-mcp",
      "env": {
        "PIHOLE_1_URL": "http://192.168.1.2",
        "PIHOLE_1_PASSWORD": "primary-password",
        "PIHOLE_1_NAME": "downstairs",
        "PIHOLE_2_URL": "http://192.168.1.3",
        "PIHOLE_2_PASSWORD": "secondary-password",
        "PIHOLE_2_NAME": "upstairs"
      }
    }
  }
}

Cada ferramenta então aceita um argumento opcional instance, e cada resultado é rotulado com a instância de onde veio. Omita o argumento para direcionar a primeira instância; passe um nome para direcionar uma específica; passe instance=all em uma ferramenta somente leitura (ex.: pihole_padd, pihole_stats_summary) para consultar todas as instâncias simultaneamente e obter um único agregado estruturado (resultados por instância mais um resumo de sucesso/fracasso — uma instância lenta ou inacessível não falha mais a chamada inteira). Ferramentas que alteram estado exigem uma única instância nomeada. PIHOLE_URL e PIHOLE_1_URL são mutuamente exclusivos.

Mantendo instâncias sincronizadas

Quando você executa mais de um Pi-hole, duas ferramentas extras aparecem para mantê-los alinhados:

• pihole_instance_diff — compara duas instâncias e mostra exatamente o que difere entre adlists/allowlists, regras de allow/deny (exatas e regex), grupos, clientes, registros A/AAAA de DNS local e registros CNAME. É somente leitura e não escreve nada.
• pihole_instance_sync — envia a configuração de uma instância de origem para um destino. É deliberadamente cauteloso:
  • Apenas uma direção. Você nomeia a fonte source da verdade e o target; apenas o destino é gravado.
  • Dry-run primeiro. Retorna um plano e um confirm_token por padrão; nada muda até você reexecutar com mode=apply e esse token. Se a configuração divergir entre o planejamento e a aplicação, o token não corresponde mais e a aplicação é recusada.
  • Adicionar/atualizar por padrão. Entradas no destino que não estão na origem são deixadas intactas, a menos que você passe prune=true.
  • Com backup. Um backup teleporter do destino é feito antes de qualquer alteração (desative com snapshot=false).
  • Seguro por omissão. Configurações específicas de host e identidade — DHCP, bindings de interface, senhas, certificados TLS, sessões, 2FA — nunca são sincronizadas. Associações de associação de grupo também não são sincronizadas, porque os IDs de grupo do Pi-hole são locais para cada instância.

Exemplo: visualize o que o Pi-hole upstairs está perdendo em relação ao downstairs, e então aplique.

pihole_instance_diff   { "source": "downstairs", "target": "upstairs" }
pihole_instance_sync   { "source": "downstairs", "target": "upstairs" }            → returns a plan + confirm_token
pihole_instance_sync   { "source": "downstairs", "target": "upstairs",
                         "mode": "apply", "confirm_token": "<token from the plan>" }

Configuração do Cliente

A configuração de Início Rápido acima funciona para a maioria dos clientes. Expanda a seção abaixo para instruções específicas do cliente.

{
  "mcpServers": {
    "pihole": {
      "command": "pihole-mcp",
      "env": {
        "PIHOLE_URL": "http://192.168.1.2",
        "PIHOLE_PASSWORD": "your-password"
      }
    }
  }
}

claude mcp add pihole \
  -e PIHOLE_URL=http://192.168.1.2 \
  -e PIHOLE_PASSWORD=your-password \
  -- pihole-mcp

claude mcp list

{
  "servers": {
    "pihole": {
      "type": "stdio",
      "command": "pihole-mcp",
      "env": {
        "PIHOLE_URL": "http://192.168.1.2",
        "PIHOLE_PASSWORD": "your-password"
      }
    }
  }
}

{
  "mcpServers": {
    "pihole": {
      "command": "pihole-mcp",
      "env": {
        "PIHOLE_URL": "http://192.168.1.2",
        "PIHOLE_PASSWORD": "your-password"
      }
    }
  }
}

{
  "mcpServers": {
    "pihole": {
      "command": "pihole-mcp",
      "env": {
        "PIHOLE_URL": "http://192.168.1.2",
        "PIHOLE_PASSWORD": "your-password"
      }
    }
  }
}

{
  "mcpServers": {
    "pihole": {
      "command": "pihole-mcp",
      "env": {
        "PIHOLE_URL": "http://192.168.1.2",
        "PIHOLE_PASSWORD": "your-password"
      }
    }
  }
}

{
  "mcpServers": {
    "pihole": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-e", "PIHOLE_URL=http://192.168.1.2",
        "-e", "PIHOLE_PASSWORD=your-password",
        "-e", "TZ=Australia/Adelaide",
        "ghcr.io/hexamatic/pihole-mcp:latest"]
    }
  }
}

Ferramentas

Um único Pi-hole expõe 76 ferramentas. Configurar mais de um adiciona pihole_instance_diff e pihole_instance_sync, totalizando 78 — elas são registradas apenas quando há uma segunda instância para comparar, então uma configuração de Pi-hole único não mostra ferramentas que não pode usar.

As tabelas abaixo são um resumo; a referência completa gerada com todos os parâmetros está em docs/TOOLS.md.

Painel

Controle de DNS

Estatísticas

Gerenciamento de Domínios

Grupos, Clientes, Listas

Log de Consultas

Sistema

Ações e Rede

Multi-instância (apenas com mais de um Pi-hole configurado)

Opções de Resposta

A maioria das ferramentas aceita parâmetros opcionais para controlar a saída:

• detail (minimal | normal | full) — Controla a profundidade da resposta. Padrão: normal. Use minimal para resumos de uma linha, full para dados completos da API.
• format (text | csv) — Formato de saída para dados tabulares. Padrão: text. CSV economiza ~29% de tokens. Disponível em pihole_domains_list, pihole_lists_list, pihole_clients_list, pihole_queries_search, pihole_network_devices, pihole_stats_top_domains, pihole_stats_top_clients, pihole_stats_upstreams, pihole_stats_query_types, pihole_stats_recent_blocked, pihole_stats_database_top_domains, pihole_stats_database_top_clients, pihole_stats_database_upstreams, pihole_dhcp_leases e pihole_config_properties.

Prompts

Fluxos de trabalho pré-construídos de várias etapas para tarefas comuns:

Recursos

Contexto somente leitura que um cliente MCP pode obter sem chamar uma ferramenta:

Com mais de um Pi-hole configurado, cada instância também é acessível diretamente — pihole://instances as lista, e pihole://<instance>/status e pihole://<instance>/summary leem uma instância nomeada. Os URIs sem prefixo acima sempre leem a primeira instância declarada.

Configuração Avançada

Transporte

Por padrão, o pihole-mcp usa stdio (padrão para MCP). Transportes HTTP e SSE também estão disponíveis:

# Default stdio (for Claude Desktop, Cursor, etc.)
pihole-mcp

# HTTP transport (for web-based MCP clients)
pihole-mcp -transport http -address localhost:8080

# SSE transport (deprecated — see below)
pihole-mcp -transport sse -address localhost:8080

SSE está obsoleto. A especificação MCP substituiu o transporte HTTP+SSE pelo Streamable HTTP na revisão de 2025-03-26. -transport sse é mantido para clientes mais antigos e ainda recebe correções de segurança, mas novas implantações devem usar -transport http. Ele será removido assim que os clientes que precisam dele migrarem.

Segurança (transportes HTTP e SSE)

Os transportes http e sse aplicam dois middlewares de segurança a cada requisição, em conformidade com as diretrizes de proteção contra rebinding de DNS da especificação MCP 2025-11-25. O stdio não é afetado (processo único, usuário único).

• Validação de Origin e Host. Ambos os cabeçalhos devem resolver para um host em PIHOLE_ALLOWED_ORIGINS (padrão apenas loopback). A ausência de Origin é permitida para clientes MCP que não são navegadores. Divergências retornam HTTP 403. Para expor o pihole-mcp em uma LAN, estenda a lista de permissões:

  export PIHOLE_ALLOWED_ORIGINS="localhost,127.0.0.1,[::1],pihole-mcp.lan"
  

  O literal * desativa totalmente a aplicação — use apenas se estiver atrás de um proxy reverso que faz seu próprio controle de acesso.

• Limitação de taxa por sessão. Um token bucket chaveado por Mcp-Session-Id (fallback para IP do cliente) limita requisições a PIHOLE_RATE_LIMIT por minuto (padrão 120, rajada max(120/4, 30)). Requisições limitadas retornam HTTP 429 com Retry-After: 1. 0 desativa.

  # Tighter limit for a small fleet
  export PIHOLE_RATE_LIMIT=60
  
  # Disable (only when running behind a proxy with its own rate limit)
  export PIHOLE_RATE_LIMIT=0
  

OpenTelemetry

O rastreamento é opcional. Defina OTEL_EXPORTER_OTLP_ENDPOINT para ativar:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
pihole-mcp

Todas as chamadas de ferramentas são rastreadas automaticamente com nome da ferramenta, duração e status de erro.

Se você não precisa de rastreamento, a build slim remove o SDK OpenTelemetry, gRPC, protobuf e dependências grpc-gateway completamente — pouco mais de 40% menor:

just build-slim
# or
go build -tags slim -o bin/pihole-mcp-slim ./cmd/pihole-mcp

# Docker
docker pull ghcr.io/hexamatic/pihole-mcp:latest-slim

O binário slim é funcionalmente idêntico, exceto que OTEL_EXPORTER_OTLP_ENDPOINT é ignorado.

Solução de Problemas

"Pi-hole rejeitou o login: o pool de sessões da API está cheio"

O Pi-hole permite um número limitado de sessões de API simultâneas — webserver.api.max_sessions, 16 por padrão — e cada cliente que faz login ocupa um lugar: a interface web, PADD, Home Assistant, qualquer outra integração e o pihole-mcp. Quando todos estão ocupados, o Pi-hole responde 429 e recusa novos logins, inclusive da própria interface web.

O pihole-mcp libera seu lugar no encerramento, mas uma sessão deixada por um processo que foi morto em vez de parado manterá o lugar até expirar. Três saídas, em ordem de preferência:

1. Libere um lugar. Peça a lista de sessões (pihole_auth_sessions) e revogue uma que esteja ociosa (pihole_auth_revoke_session).
2. Aumente o limite. Em uma máquina com poucas integrações, 16 é baixo:

   pihole-FTL --config webserver.api.max_sessions 32
   

3. Aguarde. Os lugares são liberados após webserver.session.timeout — 30 minutos por padrão.

Tentar novamente não ajudará, então o pihole-mcp não tenta: ele relata o problema em vez de travar silenciosamente.

Autenticação falha com senha correta

O Pi-hole limita a taxa de logins falhos repetidos, e o limitador não distingue entre "senha errada" e "a senha que você acabou de corrigir". Aguarde alguns segundos e tente novamente. Se persistir, confirme que você está usando a senha de administrador ou uma senha de aplicativo — não o código TOTP da interface web.

Docker: "connection refused" ao acessar o Pi-hole

localhost dentro de um contêiner é o contêiner, não o host. Aponte PIHOLE_URL para o endereço LAN do host (http://192.168.1.2), para host.docker.internal no Docker Desktop, ou coloque ambos os contêineres na mesma rede Docker e use o nome do contêiner do Pi-hole.

Timestamps exibidos em UTC

Cada timestamp na saída das ferramentas carrega um marcador de fuso explícito (ex.: 19 Jul 2026, 9:41 AM UTC), então as respostas são inequívocas independentemente do fuso. Qual fuso é usado depende de onde o servidor roda: binários nativos usam o fuso do sistema, enquanto a imagem Docker usa UTC por padrão. Para obter horários locais do contêiner, defina TZ no contêiner pihole-mcp (não apenas no do Pi-hole) — os dados de fuso estão embutidos no binário, então não são necessários pacotes extras ou montagens de volume:

environment:
  - TZ=Australia/Adelaide

Um valor não reconhecido de TZ registra um aviso na inicialização e usa UTC como fallback em vez de recusar iniciar.

"x509: certificate signed by unknown authority"

Seu Pi-hole está servindo HTTPS com um certificado autoassinado, o que falha na verificação TLS padrão. A correção certa é um certificado confiável no Pi-hole (por exemplo, via configurações de domínio integradas ou um proxy reverso com Let's Encrypt). Se isso não for prático, defina PIHOLE_TLS_SKIP_VERIFY=true para desativar a verificação — as conexões ainda são criptografadas, mas a identidade do servidor não é mais verificada, então use apenas em uma rede que você controla.

Conexões ocasionalmente interrompidas

O servidor web embutido do Pi-hole fecha conexões sob carga. O pihole-mcp tenta novamente automaticamente com backoff; se você ainda vir falhas, aumente PIHOLE_MAX_RETRIES (padrão 3).

Desenvolvimento

# Prerequisites: Go 1.26+, Docker, mise, just

# One-command setup
just setup

# Start local Pi-hole (http://localhost:8081, password: test)
just dev-up

# Run quality checks (format + lint + test)
just check

# Run integration tests against local Pi-hole
just integration

# Build binary
just build

Veja CONTRIBUTING.md para diretrizes completas de desenvolvimento.

Pi-hole é uma marca registrada da Pi-hole LLC. Este projeto é mantido de forma independente e não é afiliado, endossado ou patrocinado pela Pi-hole LLC.

Licença

MIT