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 管理を求めるすべての人に最適です。

Related MCP server: MCP Pi-hole Server

機能

• マルチインスタンス対応 - 環境変数で 1〜N 個の Pi-hole インスタンスを設定

• Pi-hole v6 API の完全カバレッジ - クエリログ、許可/拒否リスト（完全な CRUD）、グループ管理、ブロック制御、ローカル DNS（A + CNAME）レコード、gravity リロード、統計情報

• スマートな正規表現検出 - メタ文字の分析に基づいて、ドメインを完全一致リストまたは正規表現リストへ自動的に振り分け

• 正規表現ランドマイン検出器 - 正規表現であるべきなのに deny-exact に登録されているエントリ（誤分類されたルール）を検出

• Docker 対応 - 非 root ユーザー、ヘルスチェック、セキュリティ強化を備えたマルチステージ Dockerfile

• Streamable HTTP トランスポート - HTTP ベースの MCP をサポートする任意の 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

設定

設定はすべて環境変数を介して行います。完全なリファレンスは .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 内の各インスタンス名に対して、次の値を指定します:

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

利用可能な MCP ツール

すべてのツールは、特定の Pi-hole を対象とするオプションの instance パラメータを受け付けます。デフォルトでは最初に設定されたインスタンスを使用します。

MCP クライアントへの接続

サーバーは http://HOST:PORT/mcp（デフォルト: http://localhost:3000/mcp）で待ち受けます。

Claude Desktop / Claude Code

MCP 設定に追加してください:

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

Supergateway（stdio ラッパー）

MCP クライアントが stdio トランスポートのみをサポートしている場合は、supergateway を使用してください:

npx -y supergateway --streamableHttp 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