Pi-hole MCP Server

pihole-mcp

Claude などの AI アシスタントから Pi-hole v6 の DNS 広告ブロッカーを自在に操作できる、MCP（Model Context Protocol） サーバーです。クエリログ、許可／拒否リスト、グループ管理、Gravity の再読み込み、統計情報を操作できます。複数インスタンスのデプロイを前提に設計されており、単一の MCP エンドポイントから 1 台または複数台の Pi-hole インスタンスを管理できます。

なぜ使うのか

Pi-hole の管理 API は強力ですが、スクリプトから操作するには扱いにくいものです。この MCP サーバーは、Pi-hole API のすべてのアクションを、MCP 対応の AI アシスタントが直接呼び出せるツールに変換します。管理 UI をクリックしたり、curl コマンドを書いたりする代わりに、ブロックされているものの確認、ドメインの許可リストへの追加、インスタンス間の統計比較などを AI に頼むだけで済みます。

複数の Pi-hole（プライマリ＋セカンダリ、または VLAN ごと）を運用するホームラボユーザー、DNS フィルタリングを大規模に管理するネットワーク管理者、AI を活用した DNS 管理を行いたい方に最適です。

機能

• 複数インスタンス対応 - 環境変数を使って 1 台から N 台の Pi-hole インスタンスを設定できます
• Pi-hole v6 API を幅広くカバー - クエリログ、許可／拒否リスト（完全な CRUD）、グループとクライアントの管理、ブロック制御、ローカル DNS（A + CNAME）レコード、Gravity の再読み込み、統計情報
• 正規表現の自動判定 - メタ文字を分析し、ドメインを完全一致リストまたは正規表現リストに自動で振り分けます
• 正規表現の誤分類検出 - 正規表現にするべきと思われる拒否リストの完全一致エントリー（誤分類されたルール）を検出します
• Docker 対応 - 非 root ユーザー、ヘルスチェック、セキュリティ強化を備えたマルチステージ Dockerfile
• Streamable HTTP または stdio トランスポート - 長時間稼働する HTTP サービスとして実行するか、必要に応じて MCP クライアントから起動できます
• Docker secrets 対応 - パスワードは環境変数または /run/secrets/ ファイルで指定できます

クイックスタート

Docker（推奨）

git clone https://github.com/ranklancer/pihole-mcp.git
cd pihole-mcp
cp .env.example .env
# Edit .env with your Pi-hole URL(s) and password(s)

mkdir -p secrets
echo "your-pihole-password" > secrets/pihole_password
chmod 600 secrets/pihole_password

cp docker-compose.example.yml docker-compose.yml
docker compose up -d

Node.js

npm install
npm run build
export PIHOLE_INSTANCES=pihole
export PIHOLE_BASE_URL=http://pihole.example.com
export PIHOLE_PASSWORD=your-password
npm start

オンデマンドでローカル実行（stdio、Docker 不要）

必要に応じて MCP クライアントがサーバーを子プロセスとして起動し、標準入力／標準出力経由で通信します。ポートは開かず、バックグラウンドで動き続けることもありません。

npm ci
npm run build
cp .env.example .env
chmod 600 .env
# Edit .env with your Pi-hole URL(s) and password(s)

Claude Code に登録します（ユーザースコープ）：

claude mcp add --scope user pihole -- bash -c \
  'set -a; . ~/path/to/pihole-mcp/.env; set +a; MCP_TRANSPORT=stdio exec node ~/path/to/pihole-mcp/dist/index.js'

または MCP クライアントの設定に手動で追加します：

{
  "mcpServers": {
    "pihole": {
      "type": "stdio",
      "command": "bash",
      "args": ["-c", "set -a; . ~/path/to/pihole-mcp/.env; set +a; MCP_TRANSPORT=stdio exec node ~/path/to/pihole-mcp/dist/index.js"]
    }
  }
}

stdio モードでは、.env の HOST と PORT は無視されます。

設定

すべての設定は環境変数で行います。詳細については.env.exampleを参照してください。

単一インスタンス

PIHOLE_INSTANCES=pihole
PIHOLE_BASE_URL=http://192.0.2.100
PIHOLE_PASSWORD=your-password

複数インスタンス

PIHOLE_INSTANCES=primary,secondary
PRIMARY_BASE_URL=http://192.0.2.100
PRIMARY_PASSWORD=password1
SECONDARY_BASE_URL=https://198.51.100.101
SECONDARY_PASSWORD=password2
SECONDARY_INSECURE_TLS=true

PIHOLE_INSTANCES に指定した各インスタンス名について、次の変数を設定してください：

変数	必須	説明
<NAME>_BASE_URL	はい	Pi-hole のベース URL（例：http://pihole.local）
<NAME>_PASSWORD	はい	Pi-hole API のパスワード（または Docker secrets を使用）
<NAME>_INSECURE_TLS	いいえ	自己署名証明書を使用する場合は true に設定します（デフォルト：false）

Docker secrets はフォールバックとしてサポートされています：/run/secrets/<name>_password（小文字）。

利用可能な MCP ツール

ツール	説明
pihole_query_log	フィルター（件数、時間範囲、クライアントの IP アドレスまたは名前、ドメイン、ステータス）を指定してクエリログを取得します
pihole_allow_domain	許可リストに追加します（完全一致か正規表現かを自動判定します）
pihole_deny_domain	拒否リストに追加します（完全一致か正規表現かを自動判定します）
pihole_list_allowlist	許可リストのすべてのエントリーを一覧表示します（完全一致と正規表現を統合）
pihole_list_denylist	拒否リストのすべてのエントリーを一覧表示します（完全一致と正規表現を統合）
pihole_stats_summary	Pi-hole の統計概要を取得します
pihole_reload_lists	gravity の再読み込みを実行します
pihole_group_management	Pi-hole グループに対する CRUD 操作
pihole_client_management	Pi-hole クライアントとそのグループ割り当てに対する CRUD 操作
pihole_check_regex_types	拒否リストの完全一致リスト内で分類を誤っている正規表現を検出します
pihole_set_blocking	ブロッキングを有効化／無効化します。自動復帰タイマーも指定できます
pihole_domain_management	許可／拒否ドメインを更新または削除します（CRUD を完了します）
pihole_local_dns	ローカル DNS A レコードを一覧表示／追加／削除します
pihole_local_cname	ローカル CNAME レコードを一覧表示／追加／削除します

各ツールでは、特定の Pi-hole を対象にするための instance パラメーターを省略できます。デフォルトでは、最初に設定されたインスタンスが対象になります。

MCP クライアントへの接続

このセクションは HTTP トランスポート（Docker または npm start）に適用されます。stdio については、オンデマンドでローカル実行を参照してください。

サーバーは http://HOST:PORT/mcp（デフォルトは http://localhost:3000/mcp）でリッスンします。HTTP エンドポイントには認証がないため、localhost または信頼できるネットワークにバインドしてください。

Claude Desktop / Claude Code

MCP 設定に追加します：

{
  "mcpServers": {
    "pihole": {
      "url": "http://localhost:3031/mcp"
    }
  }
}

ヘルスチェック

curl http://localhost:3031/health
# {"ok":true,"service":"pihole-mcp","version":"0.3.0"}

開発

npm install
npm run dev     # Watch mode — recompiles on save
npm start       # Run the server

要件

• Node.js >= 20
• API アクセスが有効な Pi-hole v6
• Pi-hole インスタンスへのネットワーク接続

関連プロジェクト

• Pi-hole — ネットワーク全体での広告ブロック
• Model Context Protocol — AI ツール統合のためのオープン標準
• MCP Server Registry — MCP サーバーのディレクトリ

ライセンス

MIT