pihole-mcp

統合型Pi-hole v6 MCPサーバー。3つのアップストリーム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. POST /api/auth に {"password": "<app-password>"} を送信し、セッションSIDを取得します。

2. 以降のすべての呼び出しに X-FTL-SID: <sid> を含めます。

3. 401エラーまたは有効期限切れに近い場合、クライアントは再認証を行い、一度だけ再試行します。

4. シャットダウン時に DELETE /api/auth でセッションを解放します。

アプリケーションパスワードはPi-hole Web UIで作成します：Settings > Web Interface > "Application password" > Generate。これはメインの管理用Webパスワードとは別のものであり、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）を使用しています。Pi-holeは単一の製品であるため（動的な製品ロードや検出がない）、unifi-mcpよりもシンプルです。これをマルチPi-hole対応や不足機能（adlist/gravity CRUD、グループ、DHCP、Teleporter）のために拡張する場合は、unifi-mcpの機能ごとのモジュールパターンに従ってください。