🍓 pihole-mcp-serer

Pi-hole用のモデルコンテキストプロトコル（MCP）サーバー。このサーバーは、Pi-holeの機能をAIアシスタントが使用できるツールとして公開します。

依存関係

ドッカー

• Dockerインストールガイド

uv (オプション、開発用)

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

Related MCP server: MCP Pi-hole 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 up

MCP検査官

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を使用して初期設定が完了していることを前提としています。

拡張機能の設定

1. 設定メニューを開くには、 goose configureと入力します。

2. 拡張機能を追加を選択

3. リモート内線を選択

4. 名前を聞いてきます。どんな名前でも構いません。私はpihole-mcpと名付けました。

5. *「SSE エンドポイント URI は何ですか?」*と尋ねられたらhttp://localhost:8383/sseと入力します。

6. タイムアウトを入力します。

7. 必要に応じて説明を追加してください。

8. 環境変数について尋ねられたら、 **「いいえ」**を選択します。

セッションを開始する

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

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

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

ライセンス

マサチューセッツ工科大学