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.

Características

• ListLocalDNS : Devuelve todas las configuraciones de DNS locales de Pi-hole
• ListQueries : Devuelve el historial reciente de consultas DNS de Pi-hole
• Compatibilidad con varios Pi-hole : administre hasta 4 Pi-holes desde un único servidor MCP
• ...más por venir...

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.

Ambiente

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

Implementación de Docker

Ejecute el servidor MCP de Pi-hole en Docker.

Uso de Docker Compose

1. Tire y ponga en marcha el contenedor:
   docker-compose up -d
2. El servidor estará disponible en http://localhost:8383

Compilación manual de Docker

Alternativamente, puede construir y ejecutar el contenedor Docker manualmente:

Ejecutar localmente

La implementación de Docker utiliza el modo SSE para la comunicación bidireccional entre el host y el contenedor. En teoría, se podría usar el modo STDIO con Docker exec. Sin embargo, si se desea ejecutar localmente, se puede ejecutar simplemente con uv . Esto es especialmente útil para inspeccionar rápidamente herramientas y recursos con las utilidades de desarrollo mcp integradas. Por ejemplo:

Luego, en su navegador web, navegue a http://localhost:6274 .

API

Este servidor MCP expone los siguientes recursos y herramientas:

Recursos

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

Herramientas

• list_local_dns : enumera todas las configuraciones de DNS locales de Pi-hole(s)
• list_queries : obtiene el historial reciente de consultas DNS de Pi-hole(s)

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

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.

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 .

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:

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

Licencia

Instituto Tecnológico de Massachusetts (MIT)