🍓 servidor pihole-mcp

Un servidor de Protocolo de Contexto de Modelo (MCP) para Pi-hole. Este servidor expone la funcionalidad de Pi-hole como herramientas que pueden ser utilizadas por asistentes de IA.

Dependencias

Estibador

• Guía de instalación de Docker

uv (opcional, para desarrollo)

Si desea ejecutar la aplicación localmente, use uv . Instálela con el gestor de paquetes que prefiera.

Related MCP server: MCP Pi-hole Server

Ambiente

Cree un archivo .env en la raíz del proyecto con sus credenciales de Pi-hole:

# Primary Pi-hole (required)
PIHOLE_URL=https://your-pihole.local/
PIHOLE_PASSWORD=your-admin-password
#PIHOLE_NAME=Primary        # optional, defaults to URL if unset

# Secondary Pi-hole (optional)
#PIHOLE2_URL=https://secondary-pihole.local/
#PIHOLE2_PASSWORD=password2
#PIHOLE2_NAME=Secondary     # optional

# Up to 4 Pi-holes:
#PIHOLE3_URL=...
#PIHOLE3_PASSWORD=...
#PIHOLE3_NAME=...

#PIHOLE4_URL=...
#PIHOLE4_PASSWORD=...
#PIHOLE4_NAME=...

Estructura del proyecto

El proyecto sigue una organización modular para una mejor mantenibilidad:

/
├── main.py                # Main application entry point
├── tools/                 # Pi-hole tools organized by functionality
│   ├── __init__.py
│   ├── config.py          # Configuration-related tools (DNS settings)
│   └── metrics.py         # Metrics and query-related tools
├── resources/             # MCP resources
│   ├── __init__.py
│   └── common.py          # Common resources (piholes://, version://)
├── docker-compose.yml     # Docker Compose configuration for production
├── docker-compose.dev.yml # Docker Compose for development with volume mounts
└── Dockerfile             # Docker build configuration

Esta estructura separa el código en componentes lógicos manteniendo la compatibilidad con todos los modos de ejecución.

Ejecución del servidor

Hay varias formas de ejecutar el servidor MCP de Pi-hole:

Uso de Docker (recomendado para producción)

# Standard deployment
docker-compose up -d

El servidor estará disponible en http://localhost:8383

Modo de desarrollo con Docker

Para el desarrollo, utilice el archivo de composición dev que se compila localmente:

docker-compose -f docker-compose.dev.yml up

Inspector de MCP

Puede ejecutar el inspector MCP usando uv y la CLI mcp :

uv run mcp dev main.py

Esto iniciará una interfaz interactiva en http://localhost:6274 donde podrá probar herramientas y recursos.

API

Este servidor MCP expone los siguientes recursos y herramientas:

Recursos

• piholes:// : Devuelve información sobre todos los Pi-holes configurados

• version:// : Devuelve la versión del servidor MCP

• list-tools:// : Devuelve una lista de categorías de herramientas

  • list-tools://{category} : Devuelve una lista de herramientas dentro de una categoría específica

Herramientas

Cada llamada de herramienta devuelve resultados como una lista de diccionarios con la siguiente estructura:

[
  {
    "pihole": "Pi-hole Name",
    "data": [...]  # Result data from this Pi-hole
  },
  ...
]

Configuración

• list_local_dns : enumera todas las configuraciones de DNS locales de Pi-hole(s)

• add_local_a_record : agrega un registro A local a Pi-hole(s).

• add_local_cname_record : agrega un registro CNAME local a Pi-hole(s).

• remove_local_a_record : elimina todos los registros A de un nombre de host.

• remove_local_cname_record : elimina todos los registros CNAME de un nombre de host.

Métrica

• list_queries : obtiene el historial reciente de consultas DNS de Pi-hole(s)

• list_query_suggestions : Obtener sugerencias de filtros de consulta

• list_query_history : Obtener datos del gráfico de actividad para consultas a lo largo del tiempo

Pruebas en goose

Goose es un cliente CLI LLM útil para pruebas y desarrollo. Sigue sus instrucciones de instalación aquí .

Lo siguiente supone que ha completado la configuración inicial con goose configure .

Configurar extensión

1. Escriba goose configure para abrir el menú de configuración.

2. Seleccione Agregar extensión

3. Seleccionar extensión remota

4. Te pedirá un nombre. No importa cómo lo llames. Yo lo llamé pihole-mcp .

5. Cuando pregunte "¿Cuál es el URI del punto final de SSE?", ingrese http://localhost:8383/sse .

6. Introduzca un tiempo de espera.

7. Añade una descripción si lo deseas.

8. Seleccione No cuando le pregunte acerca de las variables de entorno.

Iniciar una sesión

Una vez instalado el servidor, inicie una sesión de chat.

goose session

Intente preguntarle: "¿Cuáles son mis registros DNS locales?"

...o decirle: "Muéstrame mis consultas DNS recientes".

Escritorio de Claude

El cliente de escritorio de Claude actualmente solo admite el protocolo STDIO, sin embargo, puede usar un proxy para comunicarse con el punto final SSE.

Agregue lo siguiente a su archivo claude_desktop_config.json .

{
  "mcpServers": {
    "pihole": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8383/sse"
      ]
    }
  }
}

Si se conecta a un host diferente en su red local y usa una conexión no segura, deberá permitirla explícitamente con el argumento --allow-http . Por ejemplo:

{
  "mcpServers": {
    "pihole": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://192.168.1.255:8383/sse",
        "--allow-http"
      ]
    }
  }
}

Luego, reinicia completamente la aplicación y pruébala.

Licencia

Instituto Tecnológico de Massachusetts (MIT)