🍓 pihole-mcp-serer

🍓 pihole-mcp-serer

Pi-hole 用の Model Context Protocol（MCP）サーバーです。このサーバーは、AI アシスタントが使用できるツールとして Pi-hole の機能を公開します。

依存関係

Docker

• Docker のインストールガイド

uv（任意、開発用）

アプリケーションをローカルで実行する場合は、uv を使用してください。お好みのパッケージマネージャーでインストールします。

環境

プロジェクトのルートに .env ファイルを作成し、Pi-hole の認証情報を記述します。

# 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 up

MCP Inspector

uv と mcp CLI を使用して MCP Inspector を実行できます。

uv run mcp dev main.py

http://localhost:6274 でインタラクティブなインターフェースが起動し、ツールやリソースをテストできます。

API

この MCP サーバーは、以下のリソースとツールを公開します。

リソース

• piholes://：設定されているすべての Pi-hole の情報を返します
• 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 による初期設定が完了していることを前提とします。

エクステンションの設定

1. goose configure と入力して設定メニューを開きます。
2. Add Extension を選択します。
3. Remote Extension を選択します。
4. 名前を入力するよう求められます。名前は何でもかまいません。ここでは pihole-mcp としました。
5. "What is the SSE endpoint URI?" と尋ねられたら、http://localhost:8383/sse を入力します。
6. タイムアウトを入力します。
7. 必要に応じて説明を追加します。
8. 環境変数について尋ねられたら、No を選択します。

セッションの開始

サーバーをインストールしたら、チャットセッションを開始します。

goose session

「ローカル DNS レコードは何ですか？」と尋ねてみてください。

……または、「最近の DNS クエリを表示してください」と依頼してみてください。

Claude Desktop

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"
      ]
    }
  }
}

その後、アプリケーションを完全に再起動して試してください。

ライセンス

MIT