MCP Pihole

🚀 MCP Pi-hole Server

このMCP (Model Context Protocol) サーバーは、ClaudeなどのAIアシスタントをネットワーク全体で広告をブロックするPi-holeに接続します。自然言語でDNSブロッキングの管理、統計の表示、ホワイトリスト/ブラックリストの制御などを行うことができます。

🚀 クイックスタート

このMCPサーバーを使用することで、ネットワーク上でPi-holeを実行している場合に以下のことができます。

• DNSトラフィックの監視 - クエリ統計、上位のブロックされたドメイン、クライアントのアクティビティを表示します。
• ブロッキングの制御 - 即座にまたはタイマーを使用してPi-holeのブロッキングを有効または無効にします。
• リストの管理 - ウェブUIを開かずにホワイトリストとブラックリストにドメインを追加または削除します。
• クエリログの表示 - 詳細情報を含む最近のDNSクエリを表示します。
• Pi-holeのメンテナンス - グラビティ (ブロックリスト) を更新し、DNSキャッシュをフラッシュします。

✨ 主な機能

📦 インストール

オプション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のウェブインターフェイスを開きます。
2. [設定] > [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"
      }
    }
  }
}

環境変数

💻 使用例

設定が完了したら、自然言語で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 - ブロックリスト (グラビティ) を更新します。
• pihole_flush_cache - DNSキャッシュをフラッシュします。

ASCII可視化

このサーバーは、ANSIエスケープコードを使用してターミナルに直接レンダリングされるカラフルなASCIIアートの可視化をサポートしています。

サポートされるツール

以下のツールは、オプションの visualize: true パラメータをサポートしています:

使用方法

サポートされているツールに 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エスケープコードをサポートするターミナルで表示されます)

🔧 技術詳細

開発

# 開発モードで実行 (自動リロード)
npm run watch

# 本番用にビルド
npm run build

# ビルドされたバージョンを実行
node dist/index.js

トラブルシューティング

"PIHOLE_URL and PIHOLE_PASSWORD environment variables are required"

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

"Authentication failed"

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

"API request failed: 401"

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

Connection refused

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

🤝 コントリビューション

コントリビューションは大歓迎です！詳細なガイドラインは CONTRIBUTING.md を参照してください。

📄 ライセンス

MITライセンス - 詳細は LICENSE を参照してください。

🔗 リンク

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