pihole-mcp

Унифицированный MCP-сервер для Pi-hole v6. Объединяет полезные инструменты из трех исходных MCP (aplaceforallmystuff/mcp-pihole, sbarbett/pihole-mcp-server, cwdcwd/mcp-server-pihole) в один Python-сервер, соответствующий стеку chris2ao-unifi-mcp (FastMCP + httpx + Pydantic v2).

Инструменты (28)

Статистика (8): get_stats, get_top_blocked, get_top_permitted, get_top_clients, get_query_types, get_forward_destinations, get_recent_blocked, get_history

Запросы (2): get_query_log (расширенные фильтры: временной диапазон, домен, клиент, вышестоящий сервер, курсор), get_query_suggestions

Блокировка (3): get_blocking_status, enable_blocking, disable_blocking (с опциональным таймером)

Списки доменов (6): get_whitelist, get_blacklist, add_to_whitelist, add_to_blacklist, remove_from_whitelist, remove_from_blacklist

Локальный DNS (5): list_local_dns, add_local_a_record, remove_local_a_record, add_local_cname_record, remove_local_cname_record

Обслуживание (4): update_gravity, flush_cache, flush_logs, get_tail_log

Плюс server_info.

См. docs/plans/consolidated-tool-map.md для сопоставления инструментов с конечными точками.

Related MCP server: Pi-hole MCP Server

Аутентификация

Pi-hole v6 использует аутентификацию на основе сессий. Этот сервер обрабатывает её автоматически:

1. POST /api/auth с {"password": "<app-password>"} возвращает SID сессии.

2. Все последующие вызовы включают X-FTL-SID: <sid>.

3. При получении 401 или истечении срока действия клиент повторно проходит аутентификацию и делает одну попытку повторного вызова.

4. При завершении работы DELETE /api/auth закрывает сессию.

Пароль приложения создается в веб-интерфейсе Pi-hole: Settings > Web Interface > "Application password" > Generate. Это отдельный пароль, не связанный с основным паролем администратора, и именно он является правильными учетными данными для API-клиентов.

Установка

cd /Users/chris2ao/GitProjects/chris2ao-pihole-mcp
uv sync
cp .env.example .env   # fill in PIHOLE_URL and PIHOLE_PASSWORD
uv run pytest

Или через обертку (для промышленного использования с Claude Code):

~/.claude/scripts/pihole-wrapper.sh

Регистрация в Claude Code

В файле ~/.claude.json добавьте в mcpServers:

"pihole": {
  "command": "/Users/chris2ao/.claude/scripts/pihole-wrapper.sh",
  "args": []
}

Обертка считывает ~/.claude/secrets/secrets.env для получения PIHOLE_URL и PIHOLE_PASSWORD, а затем вызывает uv run.

Разработка

• Запуск тестов: uv run pytest

• Покрытие: uv run pytest --cov --cov-report=term

• Python: 3.12+

Связь с chris2ao-unifi-mcp

Тот же стек (FastMCP, httpx, Pydantic-settings, hatchling, uv). Проще, чем unifi-mcp, так как Pi-hole — это единый продукт (нет динамической загрузки или обнаружения продуктов). Если вы расширяете этот сервер для работы с несколькими Pi-hole или для недостающих функций (CRUD списков адресов/gravity, группы, DHCP, Teleporter), следуйте паттерну «модуль на функциональность» из unifi-mcp.