🍓 pihole-mcp-serer
Pi-hole用のモデルコンテキストプロトコル（MCP）サーバー。このサーバーは、Pi-holeの機能をAIアシスタントが使用できるツールとして公開します。
依存関係
ドッカー
uv (オプション、開発用)
アプリケーションをローカルで実行したい場合は、 uvを使用してください。お好みのパッケージマネージャーでインストールしてください。
Related MCP server: MCP Server
環境
Pi-hole の資格情報を使用して、プロジェクト ルートに.envファイルを作成します。
# Primary Pi-hole (required)
PIHOLE_URL=https://your-pihole.local/
PIHOLE_PASSWORD=your-admin-password
#PIHOLE_NAME=Primary # optional, defaults to URL if unset
# Secondary Pi-hole (optional)
#PIHOLE2_URL=https://secondary-pihole.local/
#PIHOLE2_PASSWORD=password2
#PIHOLE2_NAME=Secondary # optional
# Up to 4 Pi-holes:
#PIHOLE3_URL=...
#PIHOLE3_PASSWORD=...
#PIHOLE3_NAME=...
#PIHOLE4_URL=...
#PIHOLE4_PASSWORD=...
#PIHOLE4_NAME=...プロジェクト構造
このプロジェクトは、保守性を向上させるためにモジュール構成を採用しています。
/
├── main.py # Main application entry point
├── tools/ # Pi-hole tools organized by functionality
│ ├── __init__.py
│ ├── config.py # Configuration-related tools (DNS settings)
│ └── metrics.py # Metrics and query-related tools
├── resources/ # MCP resources
│ ├── __init__.py
│ └── common.py # Common resources (piholes://, version://)
├── docker-compose.yml # Docker Compose configuration for production
├── docker-compose.dev.yml # Docker Compose for development with volume mounts
└── Dockerfile # Docker build configurationこの構造により、すべての実行モードとの互換性を維持しながら、コードを論理コンポーネントに分割します。
サーバーの実行
Pi-hole MCP サーバーを実行するにはいくつかの方法があります。
Docker の使用 (本番環境での推奨)
# Standard deployment
docker-compose up -dサーバーはhttp://localhost:8383で利用可能になります。
Dockerによる開発モード
開発の場合は、ローカルでビルドする dev Compose ファイルを使用します。
docker-compose -f docker-compose.dev.yml upMCP検査官
uvとmcp CLI を使用して MCP インスペクターを実行できます。
uv run mcp dev main.pyこれによりhttp://localhost:6274で対話型インターフェースが起動し、ツールとリソースをテストできるようになります。
API
この MCP サーバーは、次のリソースとツールを公開します。
リソース
piholes://: 設定されているすべてのPi-holesに関する情報を返しますversion://: MCPサーバーのバージョンを返しますlist-tools://: ツールカテゴリのリストを返しますlist-tools://{category}: 特定のカテゴリ内のツールのリストを返します
ツール
各ツール呼び出しは、次の構造を持つ辞書のリストとして結果を返します。
[
{
"pihole": "Pi-hole Name",
"data": [...] # Result data from this Pi-hole
},
...
]構成
list_local_dns: Pi-hole からすべてのローカル DNS 設定を一覧表示しますadd_local_a_record: Pi-hole にローカル A レコードを追加します。add_local_cname_record: Pi-hole にローカル CNAME レコードを追加します。remove_local_a_record: ホスト名のすべての A レコードを削除します。remove_local_cname_record: ホスト名のすべての CNAME レコードを削除します。
メトリクス
list_queries: Pi-holeから最近のDNSクエリ履歴を取得します。list_query_suggestions: クエリフィルタの提案を取得するlist_query_history: クエリのアクティビティグラフデータを時間経過とともに取得する
gooseでのテスト
Gooseは、テストと開発に役立つCLI LLMクライアントです。インストール手順はこちらを参照してください。
以下はgoose configureを使用して初期設定が完了していることを前提としています。
拡張機能の設定
設定メニューを開くには、
goose configureと入力します。拡張機能を追加を選択
リモート内線を選択
名前を聞いてきます。どんな名前でも構いません。私は
pihole-mcpと名付けました。*「SSE エンドポイント URI は何ですか?」*と尋ねられたら
http://localhost:8383/sseと入力します。タイムアウトを入力します。
必要に応じて説明を追加してください。
環境変数について尋ねられたら、 **「いいえ」**を選択します。
セッションを開始する
サーバーがインストールされたら、チャット セッションを開始します。
goose session*「ローカル DNS レコードとは何ですか?」*と質問してみてください。
...または、 「最近の DNS クエリを表示してください」と指示します。
クロードデスクトップ
Claude のデスクトップ クライアントは現在 STDIO プロトコルのみをサポートしていますが、プロキシを使用して SSE エンドポイントと通信することができます。
claude_desktop_config.jsonファイルに次の内容を追加します。
{
"mcpServers": {
"pihole": {
"command": "npx",
"args": [
"mcp-remote",
"http://localhost:8383/sse"
]
}
}
}ローカルネットワーク上の別のホストに接続し、セキュリティ保護されていない接続を使用している場合は、 --allow-http引数を使用して明示的に許可する必要があります。例:
{
"mcpServers": {
"pihole": {
"command": "npx",
"args": [
"mcp-remote",
"http://192.168.1.255:8383/sse",
"--allow-http"
]
}
}
}その後、アプリケーションを完全に再起動して試してください。
