mcp-pihole

MCP Pi-hole サーバー

Claude などの AI アシスタントを、ネットワーク全体の広告ブロッカーである Pi-hole に接続する MCP（Model Context Protocol）サーバーです。自然言語を使って、DNS ブロックの管理、統計情報の確認、ホワイトリスト／ブラックリストの制御などを行えます。

このツールを使う理由

ネットワークで Pi-hole を運用している場合、この MCP サーバーを使って次のことができます。

• DNS トラフィックの監視 - クエリ統計、ブロック数の多いドメイン、クライアントのアクティビティを確認
• ブロックの制御 - Pi-hole のブロック機能をすぐに、またはタイマーを設定して有効／無効化
• リストの管理 - Web UI を開かずに、ホワイトリストやブラックリストにドメインを追加または削除
• クエリログの確認 - 詳細情報を含む最近の DNS クエリを確認
• Pi-hole のメンテナンス - gravity（ブロックリスト）を更新し、DNS キャッシュをフラッシュ

機能

カテゴリ	ツール
統計情報	クエリの合計数、ブロック率、ドメイン上位、クライアント上位
ブロック制御	有効化、無効化（任意のタイマー付き）、状態確認
ドメインリスト	ホワイトリスト／ブラックリストの CRUD 操作
クエリログ	クライアント、ステータス、応答時間を含む最近の DNS クエリ
メンテナンス	gravity の更新、キャッシュのフラッシュ
視覚化	ANSI カラーを使った ASCII アートのダッシュボードと棒グラフ

前提条件

• Node.js 18+
• API が有効になっている Pi-hole v6
• Pi-hole アプリパスワード（Pi-hole の設定で生成）
• お使いのマシンから Pi-hole へのネットワークアクセス

インストール

オプション 1：npm からインストール（推奨）

npx mcp-pihole-server

グローバルにインストールする場合：

npm install -g mcp-pihole-server

オプション 2：クローンしてビルド

git clone https://github.com/aplaceforallmystuff/mcp-pihole.git
cd mcp-pihole
npm install
npm run build

設定

1. Pi-hole アプリパスワードを取得する

1. Pi-hole の Web インターフェースを開きます
2. Settings > API に移動します
3. 新しいアプリパスワードを生成します
4. パスワードをコピーします（一度しか表示されません）

2. MCP クライアントを設定する

Claude Desktop の場合

Claude Desktop の設定ファイルに追加します。

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "pihole": {
      "command": "npx",
      "args": ["-y", "mcp-pihole-server"],
      "env": {
        "PIHOLE_URL": "http://your-pihole-address:8080",
        "PIHOLE_PASSWORD": "your-app-password"
      }
    }
  }
}

Claude Code の場合

~/.claude.json に追加します。

{
  "mcpServers": {
    "pihole": {
      "command": "npx",
      "args": ["-y", "mcp-pihole-server"],
      "env": {
        "PIHOLE_URL": "http://your-pihole-address:8080",
        "PIHOLE_PASSWORD": "your-app-password"
      }
    }
  }
}

環境変数

変数	説明	例
PIHOLE_URL	Pi-hole Web インターフェースの URL	http://pihole.local:8080
PIHOLE_PASSWORD	Pi-hole アプリパスワード	設定で取得したアプリパスワード

使用例

設定が完了すると、自然言語を使って Pi-hole を操作できます。

統計情報を確認する

「Pi-hole の統計情報を見せて」

「ブロック数の多いドメインは？」

「クエリ数が最も多いクライアントは？」

ブロックを制御する

「Pi-hole のブロック機能は有効？」

「Pi-hole を 5 分間無効にして」

「Pi-hole のブロック機能を再度有効にして」

ドメインリストを管理する

「example.com をホワイトリストに追加して」

「ads.trackersite.com をブロックして」

「ホワイトリストに登録されているドメインをすべて見せて」

クエリログを確認する

「直近 50 件の DNS クエリを見せて」

「私のスマートフォンはどのドメインにクエリを送信している？」

ビジュアルダッシュボード

「visualize: true を指定して Pi-hole の統計情報を見せて」

「視覚化して、ブロック数の多いドメインを取得して」

利用可能なツール

統計情報

• pihole_get_stats - Pi-hole の包括的な統計情報を取得
• pihole_get_top_blocked - ブロック数の多いドメインを取得
• pihole_get_top_permitted - 許可数の多いドメインを取得
• pihole_get_top_clients - クエリ数で上位のクライアントを取得
• pihole_get_query_log - 最近の DNS クエリを取得

ブロッキング制御

• pihole_get_blocking_status - ブロッキングが有効かどうかを確認します
• pihole_enable_blocking - DNS ブロッキングを有効にします
• pihole_disable_blocking - ブロッキングを無効にします（タイマーを指定することもできます）

ドメイン管理

• pihole_get_whitelist - ホワイトリストに登録されたすべてのドメインを一覧表示します
• pihole_get_blacklist - ブラックリストに登録されたすべてのドメインを一覧表示します
• pihole_add_to_whitelist - ドメインをホワイトリストに追加します
• pihole_add_to_blacklist - ドメインをブラックリストに追加します
• pihole_remove_from_whitelist - ドメインをホワイトリストから削除します
• pihole_remove_from_blacklist - ドメインをブラックリストから削除します

メンテナンス

• pihole_update_gravity - ブロックリストを更新します（gravity）
• pihole_flush_cache - DNS キャッシュをフラッシュします

ASCII ビジュアライゼーション

このサーバーでは、ANSI エスケープコードを使って、ターミナル上にカラーの ASCII アートによるビジュアライゼーションを直接表示できます。

対応ツール

次のツールは、オプションの visualize: true パラメーターに対応しています。

ツール	ビジュアライゼーション
pihole_get_stats	概要統計、上位クライアント、ブロックされたドメイン、許可されたドメインを含む全体ダッシュボード
pihole_get_top_blocked	ブロックされたドメインの赤い棒グラフ
pihole_get_top_permitted	許可されたドメインの緑の棒グラフ
pihole_get_top_clients	クライアントのアクティビティを示す青い棒グラフ

使用方法

対応するツールに visualize: true を渡します。

{
  "name": "pihole_get_stats",
  "arguments": {
    "visualize": true
  }
}

visualize が設定されていない場合、または false の場合、ツールは通常どおり JSON データを返します。

出力例

╔════════════════════════════════════════════════════════════════════════════╗
║                         🛡️  PI-HOLE DASHBOARD                          ║
╠════════════════════════════════════════════════════════════════════════════╣
║                                                                            ║
║ 📊 SUMMARY                                                                 ║
║ ────────────────────────────────────────────────────────────────────────── ║
║ Total Queries:      73K             Domains Blocked:    2.4M               ║
║ Blocked:            22K             Active Clients:     28                 ║
║ Block Rate:         29.7%           Total Clients:      115                ║
╠════════════════════════════════════════════════════════════════════════════╣
║ 🔝 TOP CLIENTS                                                             ║
║ ────────────────────────────────────────────────────────────────────────── ║
║ 192.168.1.52     ████████████████████████████████████████   28K (38%)      ║
║ 192.168.1.51     ███████████████████▋                       14K (19%)      ║
╚════════════════════════════════════════════════════════════════════════════╝

（ANSI エスケープコードに対応したターミナルで色が表示されます）

開発

# Run in development mode (auto-reloads)
npm run watch

# Build for production
npm run build

# Run the built version
node dist/index.js

トラブルシューティング

「PIHOLE_URL and PIHOLE_PASSWORD environment variables are required」

MCP 設定で両方の環境変数が設定されていることを確認してください。

「Authentication failed」

アプリのパスワードが無効か、期限切れです。Pi-hole の Settings > API から新しいパスワードを生成してください。

「API request failed: 401」

セッションの有効期限が切れています。サーバーは自動的に再認証しますが、問題が続く場合はパスワードを確認してください。

接続が拒否される

Pi-hole が実行中で、URL が正しいことを確認してください。お使いのマシンから Pi-hole のウェブインターフェースにアクセスできることも確認してください。

貢献

コントリビューションを歓迎します！ガイドラインについては、CONTRIBUTING.md をご覧ください。

ライセンス

MIT License - 詳細については LICENSE をご覧ください。

リンク

• Pi-hole
• Pi-hole Documentation
• Model Context Protocol
• MCP Specification