pihole-mcp

통합 Pi-hole v6 MCP 서버입니다. 세 개의 업스트림 MCP(aplaceforallmystuff/mcp-pihole, sbarbett/pihole-mcp-server, cwdcwd/mcp-server-pihole)의 유용한 도구들을 chris2ao-unifi-mcp 스택(FastMCP + httpx + Pydantic v2)과 일치하는 하나의 Python 서버로 통합했습니다.

도구 (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. {"password": "<app-password>"}를 포함한 POST /api/auth 요청은 세션 SID를 반환합니다.

2. 이후의 모든 호출에는 X-FTL-SID: <sid>가 포함됩니다.

3. 401 오류가 발생하거나 세션이 만료될 경우, 클라이언트는 재인증을 수행하고 한 번 재시도합니다.

4. 종료 시 DELETE /api/auth를 통해 세션을 해제합니다.

앱 비밀번호는 Pi-hole 웹 UI에서 생성합니다: 설정 > 웹 인터페이스 > "애플리케이션 비밀번호" > 생성. 이는 메인 관리자 웹 비밀번호와는 별개이며 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": []
}

래퍼는 PIHOLE_URL 및 PIHOLE_PASSWORD를 위해 ~/.claude/secrets/secrets.env를 소싱한 후 uv run을 호출합니다.

개발

• 테스트 실행: uv run pytest

• 커버리지: uv run pytest --cov --cov-report=term

• Python: 3.12+

chris2ao-unifi-mcp와의 관계

동일한 스택(FastMCP, httpx, Pydantic-settings, hatchling, uv)을 사용합니다. Pi-hole은 단일 제품(동적 제품 로딩이나 검색 없음)이므로 unifi-mcp보다 단순합니다. 다중 Pi-hole 환경이나 추가 기능(adlist/gravity CRUD, 그룹, DHCP, Teleporter)을 위해 확장하려면 unifi-mcp의 기능별 모듈 패턴을 따르세요.