Pi-hole MCP Server

pihole-mcp

Pi-hole v6 向けの、本番環境対応の MCP サーバーです。

82 個のツール（2 つ目のインスタンスでは 84 個） | 9 個のプロンプト | 5 個のリソース | 複数インスタンス対応＋同期 | 読み取り専用モード＋ツールセット | 単一の Go バイナリ

AI アシスタントから Pi-hole インスタンスを完全に操作できます。DNS ブロック、ドメイン管理、クエリ分析、統計、ネットワークデバイス、DHCP、システム管理に対応しています。Pi-hole v6 REST API と互換性があります。

このサーバーを選ぶ理由

• 制限をかけて実行できます。 PIHOLE_READ_ONLY=true を設定すると、何も変更できないツールだけが公開されます。この制限は、クライアントがたまたまキャッシュしているツール一覧だけでなく、すべての呼び出しで適用されます。さらに PIHOLE_TOOLSETS を設定すると必要な機能群だけに絞り込めるため、クライアントが「何を使えますか」と尋ねたときの応答を、より小さく低コストにできます。
• 82 個のツール（2 つ目の Pi-hole を設定すると 84 個）で、Pi-hole v6 REST API の約 95％をカバーします。ドメイン、リスト、グループ、クライアント、DHCP、ネットワーク、クエリログ、設定、ローカル DNS レコード、teleporter によるバックアップと復元、セッション管理などに対応しています。
• 複数インスタンスの差分比較と同期に対応しています。 2 つの Pi-hole を比較して違いを正確に確認したり、ドライランの計画と確認トークンを使って、一方の設定をもう一方に反映したりできます。実際に変更が書き込まれる前に確認できます。
• リリースには署名と証明書が付属します。単にビルドするだけではありません。 すべてのアーカイブとコンテナイメージに、キーレスの cosign 署名、SPDX SBOM、SLSA ビルド来歴が付属します。SECURITY.md には、それぞれを確認するための 1 行のコマンドが記載されています。
• io.github.hexamatic/pihole-mcp として公式 MCP Registry に登録されており、レジストリからのインストールに対応する任意のクライアントで、名前を指定してインストールできます。
• リリース開始から 5 か月間で 9 回のリリースを提供しています。それぞれのリリースノートには、変更内容とその理由が実際に記載されており、コミットハッシュの羅列ではありません。

クイックスタート

ほとんどの MCP クライアントで同じ設定形式を使用できます。クライアントの設定に次の内容を追加してください。

{
  "mcpServers": {
    "pihole": {
      "command": "pihole-mcp",
      "env": {
        "PIHOLE_URL": "http://192.168.1.2",
        "PIHOLE_PASSWORD": "your-password"
      }
    }
  }
}

次に、以下のいずれかの方法でバイナリをインストールします。

質問できること

大切なのはツール名ではなく、自然言語で質問することです。実際に入力する質問の例をいくつか紹介します。

変更が加えられるリスクなしで質問したい場合は、まず PIHOLE_READ_ONLY=true を設定してください。ツールの適用範囲の設定を参照してください。

インストール

MCP Registry

pihole-mcp は公式 MCP Registryに次の名前で登録されています。

io.github.hexamatic/pihole-mcp

レジストリからのインストールに対応しているクライアントは、この名前を指定して追加できます。その際、PIHOLE_URL と PIHOLE_PASSWORD の入力が求められます。登録先は ghcr.io のイメージを指しているため、クライアントで Docker が動作している必要があります。

Homebrew

brew install hexamatic/tap/pihole-mcp

macOS と Linux（Linux 版 Homebrew）の両方にインストールできます。macOS では、インストール時に cask が隔離属性を解除するため、Gatekeeper の確認なしでバイナリを実行できます。

Scoop（Windows）

scoop bucket add hexamatic https://github.com/hexamatic/scoop-bucket
scoop install pihole-mcp

Go Install

go install github.com/hexamatic/pihole-mcp/cmd/pihole-mcp@latest

Docker

docker pull ghcr.io/hexamatic/pihole-mcp:latest

Linux Packages

Debian 系（Ubuntu、Raspberry Pi OS）および RPM 系（Fedora、RHEL）のディストリビューション向け .deb および .rpm パッケージは、Releasesページから入手できます。

# Debian / Ubuntu / Raspberry Pi OS
sudo dpkg -i pihole-mcp_X.Y.Z_linux_amd64.deb

# Fedora / RHEL / CentOS
sudo rpm -i pihole-mcp_X.Y.Z_linux_amd64.rpm

バイナリのダウンロード

Linux、macOS、Windows（amd64 および arm64）向けのビルド済みバイナリは、Releasesページから入手できます。

リリースにはチェックサムが付与され、キーレス cosign で署名されています。また、SPDX SBOM と SLSA ビルド来歴も含まれています。検証用コマンドについては、SECURITY.mdを参照してください。

セットアップの確認

インストールと設定が完了したら、-check を付けてサーバーを直接実行してください。設定を読み込み、設定済みのすべての Pi-hole に接続して、それぞれを名前とともに報告します。

PIHOLE_URL=http://192.168.1.2 PIHOLE_PASSWORD=your-password pihole-mcp -check

pihole-mcp 0.9.0

PASS  primary (http://192.168.1.2)  core v6.1.4, FTL v6.7

All 1 instance(s) reachable and authenticated.

いずれかのインスタンスで失敗すると、ゼロ以外の終了コードを返し、変更が必要な項目を表示します。サーバーをクライアントに接続する前に実行することをおすすめします。ほとんどのクライアントではサーバーの出力が表示されないため、URL やパスワードが間違っている場合、サーバーが起動しなかった場合と見分けがつきません。

設定

自動化にはアプリケーションパスワードをおすすめします。TOTP 2FA を回避でき、個別に失効させることもできます。

PIHOLE_HTTP_AUTH_TOKEN、PIHOLE_HTTP_AUTH_TOKEN_FILE、PIHOLE_RATE_LIMIT、PIHOLE_ALLOWED_ORIGINS、PIHOLE_TRUSTED_PROXIES は http および sse トランスポートにのみ適用されます。stdio は定義上、単一プロセス・単一ユーザーのチャネルであり、制限はありません。いずれかのトランスポートをループバックの外部に公開する前に、セキュリティを参照してください。

ツールの範囲を絞る

デフォルトでは、サーバーは Pi-hole を変更する 34 個と破壊的な操作を行う 27 個を含む、すべてのツールを提供します。2 つの変数で範囲を絞れます。

PIHOLE_READ_ONLY=true を設定すると、何も変更できないツールのみが公開されます。書き込みツールは tools/list に表示されず、呼び出された場合も拒否されるため、キャッシュ済みの一覧を使うクライアントからも実行できません。

PIHOLE_READ_ONLY=true    # 49 tools instead of 82

PIHOLE_TOOLSETS は、どのツール群を利用可能にするかを選択します。tools/list の取得コストは会話ごとに発生するため、これだけでも設定する価値があります。

PIHOLE_TOOLSETS=dashboard,domains,lists    # blocklist curation, and nothing else
PIHOLE_TOOLSETS=all                        # the default, stated explicitly

この 2 つは組み合わせて適用され、常に読み取り専用の設定が優先されます。PIHOLE_READ_ONLY=true と PIHOLE_TOOLSETS=dns,stats を設定すると、それらのツールセットに含まれ、かつ読み取り専用である 14 個のツールが利用可能になります。

ツールセット名、それぞれに含まれる内容とツール数については、サーバーがフィルタリングに使用するものと同じテーブルから生成されるdocs/TOOLS.mdを参照してください。不明な名前を指定すると起動時にエラーとなり、有効な名前がすべて表示されます。pihole-mcp -check を実行すると、有効な名前と、実際の設定で公開されるツール数を確認できます。

scope: read-only=true, toolsets=dns,stats  14 of 82 tools exposed

一度公開されたツールセット名が削除、変更、または範囲縮小されることはありません。詳細についてはCONTRIBUTING.mdを参照してください。

複数のインスタンス

複数の Pi-hole を管理するには、PIHOLE_URL／PIHOLE_PASSWORD の代わりに、番号付きインスタンスを設定します。

{
  "mcpServers": {
    "pihole": {
      "command": "pihole-mcp",
      "env": {
        "PIHOLE_1_URL": "http://192.168.1.2",
        "PIHOLE_1_PASSWORD": "primary-password",
        "PIHOLE_1_NAME": "downstairs",
        "PIHOLE_2_URL": "http://192.168.1.3",
        "PIHOLE_2_PASSWORD": "secondary-password",
        "PIHOLE_2_NAME": "upstairs"
      }
    }
  }
}

すべてのツールで省略可能な instance 引数を指定でき、各結果には取得元のインスタンスが表示されます。最初のインスタンスを対象にする場合は引数を省略します。特定のインスタンスを対象にするには名前を指定します。読み取り専用ツール（例：pihole_padd、pihole_stats_summary）で instance=all を指定すると、すべてのインスタンスに対して並行してクエリを実行し、単一の構造化された集約結果（インスタンスごとの結果と成功／失敗の概要）を取得できます。そのため、1 つのインスタンスの応答が遅い、または到達できない場合でも、呼び出し全体が失敗することはありません。状態を変更するツールでは、インスタンスを 1 つだけ指定する必要があります。PIHOLE_URL と PIHOLE_1_URL は同時に指定できません。

インスタンスの同期

複数の Pi-hole を実行すると、設定を揃えるためのツールが 2 つ追加されます。

• pihole_instance_diff：2 つのインスタンスを比較し、広告リスト／許可リスト、許可／拒否ルール（完全一致および正規表現）、グループ、クライアント、ローカル DNS の A／AAAA レコード、CNAME レコードの相違点を確認します。読み取り専用で、何も書き込みません。
• pihole_instance_sync：ソースインスタンスの設定をターゲットに反映します。慎重に動作するよう設計されています。
  • 一方向のみです。 正とする source と target を指定します。書き込み先は常にターゲットだけです。
  • まずドライランを実行します。 デフォルトではプランと confirm_token を返し、この時点では何も変更されません。そのトークンを指定して mode=apply で再実行すると、変更が適用されます。プラン作成後、適用までの間に設定に差分が生じた場合はトークンが一致しなくなり、適用は拒否されます。
  • デフォルトでは追加／更新のみです。 prune=true を指定しない限り、ソースには存在せずターゲットに存在する項目はそのまま残ります。
  • バックアップを作成します。 変更を加える前にターゲットのテレポーターバックアップを作成します（snapshot=false で無効にできます）。
  • 対象外にすることで安全性を確保します。 ホスト固有の設定と ID 設定（DHCP、インターフェースのバインド、パスワード、TLS 証明書、セッション、2FA）は同期されません。また、Pi-hole のグループ ID は各インスタンス内で固有のため、グループのメンバーシップ関連付けも同期されません。

例：downstairs と比較して upstairs の Pi-hole に不足している設定をプレビューし、その後適用します。

pihole_instance_diff   { "source": "downstairs", "target": "upstairs" }
pihole_instance_sync   { "source": "downstairs", "target": "upstairs" }            → returns a plan + confirm_token
pihole_instance_sync   { "source": "downstairs", "target": "upstairs",
                         "mode": "apply", "confirm_token": "<token from the plan>" }

クライアントの設定

上記のクイックスタートの設定は、ほとんどのクライアントで使用できます。クライアント固有の手順は、以下のセクションを展開してください。

{
  "mcpServers": {
    "pihole": {
      "command": "pihole-mcp",
      "env": {
        "PIHOLE_URL": "http://192.168.1.2",
        "PIHOLE_PASSWORD": "your-password"
      }
    }
  }
}

claude mcp add pihole \
  -e PIHOLE_URL=http://192.168.1.2 \
  -e PIHOLE_PASSWORD=your-password \
  -- pihole-mcp

claude mcp list

{
  "servers": {
    "pihole": {
      "type": "stdio",
      "command": "pihole-mcp",
      "env": {
        "PIHOLE_URL": "http://192.168.1.2",
        "PIHOLE_PASSWORD": "your-password"
      }
    }
  }
}

{
  "mcpServers": {
    "pihole": {
      "command": "pihole-mcp",
      "env": {
        "PIHOLE_URL": "http://192.168.1.2",
        "PIHOLE_PASSWORD": "your-password"
      }
    }
  }
}

{
  "mcpServers": {
    "pihole": {
      "command": "pihole-mcp",
      "env": {
        "PIHOLE_URL": "http://192.168.1.2",
        "PIHOLE_PASSWORD": "your-password"
      }
    }
  }
}

{
  "mcpServers": {
    "pihole": {
      "command": "pihole-mcp",
      "env": {
        "PIHOLE_URL": "http://192.168.1.2",
        "PIHOLE_PASSWORD": "your-password"
      }
    }
  }
}

{
  "mcpServers": {
    "pihole": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-e", "PIHOLE_URL=http://192.168.1.2",
        "-e", "PIHOLE_PASSWORD=your-password",
        "-e", "TZ=Australia/Adelaide",
        "-v", "/host/path/for/backups:/backups",
        "ghcr.io/hexamatic/pihole-mcp:latest"]
    }
  }
}

docker run --rm \
  -e PIHOLE_URL=http://192.168.1.2 \
  -e PIHOLE_PASSWORD=your-password \
  ghcr.io/hexamatic/pihole-mcp:latest -check

ツール

単一の Pi-hole では、82 個のツールが公開されます。複数の Pi-hole を設定すると pihole_instance_diff と pihole_instance_sync が追加され、合計 84 個になります。この 2 つは比較対象となる 2 台目のインスタンスがある場合にのみ登録されるため、単一の Pi-hole 構成では使用できないツールは表示されません。

公開するツールを減らす方法については、ツールの公開範囲を絞るを参照してください。

以下の表は概要です。すべてのパラメーターを含む完全な生成リファレンスは、docs/TOOLS.md にあります。

ダッシュボード

DNS 制御

ローカル DNS

統計

ドメイン管理

グループ、クライアント、リスト

クエリログ

システム

アクションとネットワーク

複数インスタンス（Pi-hole が複数設定されている場合のみ）

応答オプション

出力を制御するための省略可能なパラメーターを受け付けるツールがあります。

• detail（minimal | normal | full）：応答の詳細度を制御します。デフォルト：normal。1行の要約にはminimalを、API データをすべて取得するにはfullを使用します。15個のツールで利用できます。
• format（text | csv）：表形式データの出力形式です。デフォルト：text。CSV を使用すると、ツールや行数に応じて、デフォルトのテキスト表示よりトークンを約8～23％節約できます。22個のツールで利用できます：pihole_domains_list、pihole_groups_list、pihole_lists_list、pihole_clients_list、pihole_queries_search、pihole_network_devices、pihole_dhcp_leases、pihole_config_properties、pihole_local_dns_list、pihole_local_cname_list、pihole_stats_top_domains、pihole_stats_top_clients、pihole_stats_upstreams、pihole_stats_query_types、pihole_stats_recent_blocked、pihole_stats_database_top_domains、pihole_stats_database_top_clients、pihole_stats_database_upstreams、pihole_history_graph、pihole_history_clients、pihole_history_database、pihole_history_database_clients。

プロンプト

一般的なタスク向けに、あらかじめ用意された複数ステップのワークフローです。

リソース

MCP クライアントがツールを呼び出さずに取得できる読み取り専用のコンテキストです。

Pi-hole が複数設定されている場合、各インスタンスにも直接アクセスできます。pihole://instancesにはインスタンスの一覧が表示され、pihole://<instance>/statusとpihole://<instance>/summaryでは名前を指定したインスタンスの情報を取得できます。上記のプレフィックスなし URI は、常に最初に宣言されたインスタンスの情報を取得します。

詳細設定

トランスポート

デフォルトでは、pihole-mcp は stdio（MCP の標準）を使用します。HTTP と SSE のトランスポートも利用できます。

# Default stdio (for Claude Desktop, Cursor, etc.)
pihole-mcp

# HTTP transport (for web-based MCP clients)
pihole-mcp -transport http -address localhost:8080

# SSE transport (deprecated, see below)
pihole-mcp -transport sse -address localhost:8080

どちらの例もループバックにバインドされるため、このマシンからのみアクセスできます。変更する前に、以下の セキュリティをお読みください。トークンを設定するまでは、どちらのトランスポートも認証を行いません。

pihole-mcp は MCP プロトコルリビジョン 2025-11-25 を実装しており、古いクライアント向けにダウンネゴシエーションを行います（2025-06-18、2025-03-26、2024-11-05 はすべて受け入れられます）。

SSE は非推奨です。 HTTP+SSE トランスポートは 2025-03-26 リビジョンで Streamable HTTP に置き換えられ、仕様の機能ライフサイクルポリシーに基づき正式に 非推奨 と再分類されました（SEP-2596）。つまり、削除が提案される可能性が生じる前に、少なくとも 12 か月間は仕様の一部として完全にサポートされます。-transport sse は古いクライアント向けに維持され、引き続きセキュリティ修正が適用されますが、新規のデプロイでは -transport http を使用してください。

セキュリティ（HTTP および SSE トランスポート）

http および sse トランスポートは、認証を設定するまで認証を行いません。 stdio には影響ありません。stdio は定義上、単一プロセス・単一ユーザーのチャネルです。

デフォルトのリッスンアドレスは localhost:8080 なので、初期状態ではこのマシンからのみサーバーにアクセスできます。トークンを設定せずにバインドアドレスを変更すると、ポートにアクセスできる人は誰でも Pi-hole を制御できます。ブロックを無効にしたり、ブロックリストを書き換えたり、ネットワーク上のすべての DNS クエリを読み取ったりできます。

• ベアラー認証（バインドアドレスがループバック以外の場合は推奨）。 共有トークンを設定すると、すべてのリクエストで Authorization: Bearer ヘッダーを送信する必要があります。トークンのないリクエストには、ほかの処理を実行する前に 401 を返します。トークンは 16 文字以上である必要があります。

  export PIHOLE_HTTP_AUTH_TOKEN="$(openssl rand -base64 32)"
  # A bind beyond loopback needs the allowlist extended too, or clients reach a
  # 403 from the Host check before the token is ever looked at.
  export PIHOLE_ALLOWED_ORIGINS="localhost,127.0.0.1,[::1],192.168.1.10"
  pihole-mcp -transport http -address 0.0.0.0:8080
  

  コマンドラインで設定した環境変数は、ホスト上のすべてのユーザーが ps で確認できるため、代わりにファイルからトークンを読み込めます。コンテナプラットフォームでシークレットをマウントする際も、同じ形式を使用します。

  export PIHOLE_HTTP_AUTH_TOKEN_FILE=/run/secrets/pihole-mcp-token
  

  どちらか一方だけを設定し、両方は設定しないでください。トークンは一定時間で比較されるため、誤ったトークンを入力しても、攻撃者はどこまで一致していたかを知ることができません。拒否されたリクエストは、アドレスごとに約 20 回、その後は毎秒 1 回の別枠の認証失敗回数制限の対象となります。そのため、トークンを全速力で推測することはできず、誤ったトークンの大量送信で、同じアドレスから正しいトークンを持つクライアントが妨害されることもありません。また、サーバーは試行のたびではなく、スロットリングについて一度だけログに記録します。

  ループバック以外のアドレスにトークンなしでバインドした場合、起動時にエラーがログに記録されますが、処理は継続します。認証を行うリバースプロキシの背後に配置するのは正当なデプロイ方法であるため、起動を拒否することはありません。

• Origin と Host の検証。 両方のヘッダーは PIHOLE_ALLOWED_ORIGINS（デフォルトはループバックのみ）に含まれるホストに解決される必要があります。一致しない場合は 403 を返します。ブラウザー以外の MCP クライアントは Origin を送信しないため、Origin がない場合は許可されます。

  これは認証ではありません。 DNS リバインディング対策であり、ブラウザーのみを保護します。被害者がアクセスしたページから、そのブラウザーに許可リストが受け入れる Origin を付与することはできません。どちらのヘッダーも呼び出し元が選択できるため、ブラウザー以外のクライアントは、許可リストで指定された値を自由に設定できます。アクセス制御には PIHOLE_HTTP_AUTH_TOKEN を使用してください。

  export PIHOLE_ALLOWED_ORIGINS="localhost,127.0.0.1,[::1],pihole-mcp.lan"
  

  リテラルの * を指定すると、検証が完全に無効になります。リバースプロキシの背後に配置する場合や、ベアラートークンを設定している場合には妥当ですが、それ以外では使用しないでください。

• レート制限。 クライアントアドレスごとのトークンバケットがあり、その下に MCP セッションごとのトークンバケットがあります。PIHOLE_RATE_LIMIT（デフォルトは 120、バーストは max(120/4, 30)）がセッションごとのレートです。1 つのアドレスからは、その 4 倍のリクエストを送信できます。スロットリングされたリクエストには Retry-After: 1 を付けて 429 を返します。0 を指定すると無効になります。 呼び出し元を実際に制限するのはアドレスの上限です。Mcp-Session-Id はクライアントが書き込むヘッダーであるため、上限がなければ、リクエストごとに新しいセッション ID を送信する呼び出し元はまったく制限されません。また、MCP のリビジョン 2026-07-28 では、このヘッダーがトランスポートから削除される予定で、その後は上限が唯一の制限手段になります。セッションバケットで拒否されるリクエストも含め、すべてのリクエストがまず上限に加算されます。そのため、すでにスロットリングされているクライアントも、隣接するクライアントと共有する予算を消費し続けます。IPv6 クライアントは /64 単位でカウントされます。1 台のホストに /64 全体が割り当てられることは珍しくないためです。

  # Tighter limit for a small fleet
  export PIHOLE_RATE_LIMIT=60
  
  # Disable (only when running behind a proxy with its own rate limit)
  export PIHOLE_RATE_LIMIT=0
  

• リバースプロキシの背後で使用する場合。 デフォルトでは、クライアントアドレスは接続元のピアアドレスです。プロキシの背後ではプロキシ自身のアドレスになるため、プロキシ経由のすべてのクライアントが同じ上限を共有します。プロキシのネットワークを指定すると、X-Forwarded-For が使われます。右端から確認し、登録済みのプロキシではない最初のエントリーが採用されます。

  export PIHOLE_TRUSTED_PROXIES="192.168.1.5"
  

  デフォルトでは意図的に何も信頼されません。X-Forwarded-For はクライアントが指定できるため、無条件に信頼するサーバーでは、すべての呼び出し元が自分のレート制限バケットを選べてしまいます。**指定したプレフィックス内のすべてのホストにその権限が与えられます。**可能な限り個々のプロキシを指定し、CIDR ブロックはデプロイ環境で許容される範囲内でできるだけ絞ってください。10.0.0.0/8 を指定すると、ネットワーク全体を信頼することになります。

OpenTelemetry

トレースはオプトインです。有効にするには OTEL_EXPORTER_OTLP_ENDPOINT を設定します。

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
pihole-mcp

すべてのツール呼び出しが、ツール名、所要時間、エラー状態とともに自動的にトレースされます。

トレースが不要な場合、スリムビルドでは OpenTelemetry SDK、gRPC、protobuf、grpc-gateway の依存関係が完全に除外されます。バイナリのサイズは 43% 小さくなります。

v0.9.0 リリースのアセットから測定しています。ここでの MB は 100 万バイトを表し、イメージの数値は docker images が報告する linux/arm64 イメージの展開後サイズです。Raspberry Pi が取得するイメージです。

just build-slim
# or
go build -tags slim -o bin/pihole-mcp-slim ./cmd/pihole-mcp

# Docker
docker pull ghcr.io/hexamatic/pihole-mcp:latest-slim

スリムバイナリは機能的には同一ですが、OTEL_EXPORTER_OTLP_ENDPOINT は無視されます。

トラブルシューティング

「Pi-hole がログインを拒否しました：API セッションプールが満杯です」

Pi-hole が許可する同時 API セッション数には上限（webserver.api.max_sessions、デフォルトは 16）があり、ログインするクライアントはすべて枠を 1 つ使用します。Web インターフェース、PADD、Home Assistant、その他の統合機能、pihole-mcp が対象です。すべての枠が埋まると、Pi-hole は 429 を返し、自身の Web インターフェースからのログインも含め、それ以降のログインを拒否します。

pihole-mcp はシャットダウン時に枠を解放しますが、停止ではなく強制終了されたプロセスが残したセッションは、期限切れになるまで枠を占有します。対処方法は、優先度の高い順に次の 3 つです。

1. 枠を空ける。 セッション一覧（pihole_auth_sessions）を取得し、アイドル状態のセッションを取り消します（pihole_auth_revoke_session）。
2. 上限を引き上げる。 統合機能がいくつか動作しているマシンでは、16 は少ない値です。

   pihole-FTL --config webserver.api.max_sessions 32
   

3. 待つ。 webserver.session.timeout（デフォルトは 30 分）の経過後、枠は自動的に解放されます。

再試行しても解決しないため、pihole-mcp は再試行せず、問題を黙って放置するのではなく報告します。

正しいパスワードを入力しても認証に失敗する

Pi-hole はログイン失敗が繰り返されるとレート制限を適用します。この制限では、「パスワードが間違っている」場合と「修正したばかりのパスワード」の場合を区別しません。数秒待ってからもう一度試してください。問題が続く場合は、Web インターフェースの TOTP コードではなく、管理者パスワードまたはアプリケーションパスワードを使っていることを確認してください。

Docker：「Pi-hole への接続が拒否されました」

コンテナ内の localhost はホストではなく、そのコンテナを指します。PIHOLE_URL にホストの LAN アドレス（http://192.168.1.2）か、Docker Desktop の場合は host.docker.internal を指定してください。または、両方のコンテナを同じ Docker ネットワークに配置し、Pi-hole コンテナ名を使用してください。

タイムスタンプは UTC で表示されます

ツールの出力に含まれるすべてのタイムスタンプには、明示的なタイムゾーンマーカー（例：19 Jul 2026, 9:41 AM UTC）が付いているため、どのタイムゾーンでも曖昧さはありません。使用されるタイムゾーンはサーバーの実行環境によって異なります。ネイティブバイナリではシステムのタイムゾーンが使われますが、Docker イメージのデフォルトは UTC です。コンテナから現地時刻を取得するには、Pi-hole のコンテナだけではなく、pihole-mcp コンテナに TZ を設定してください。タイムゾーンデータはバイナリに組み込まれているため、追加のパッケージやボリュームマウントは不要です。

environment:
  - TZ=Australia/Adelaide

認識できない TZ 値を指定すると、起動時に警告がログに記録され、起動を拒否するのではなく UTC にフォールバックします。

「x509: certificate signed by unknown authority」

Pi-hole が自己署名証明書で HTTPS を提供しているため、標準の TLS 検証に失敗しています。適切な対処方法は、Pi-hole に信頼できる証明書を設定することです（組み込みのドメイン設定を利用する方法や、Let's Encrypt を使ったリバースプロキシを利用する方法があります）。それが難しい場合は、PIHOLE_TLS_SKIP_VERIFY=true を設定して検証を無効にしてください。接続は引き続き暗号化されますが、サーバーの身元は確認されなくなるため、ご自身が管理するネットワークでのみ使用してください。

接続がまれに切断される

Pi-hole の組み込みウェブサーバーは、負荷がかかると接続を閉じることがあります。pihole-mcp はバックオフを行いながら自動的に再試行します。それでも失敗する場合は、PIHOLE_MAX_RETRIES（デフォルトは 3）の値を増やしてください。

ヘルプを得る

• 使い方についての質問ですか？ Q&A Discussions で質問してください。同じ質問を持つ人が、後からそこで回答を見つけられます。
• バグを見つけた場合や、機能を提案したい場合は？ issue を作成してください。
• セキュリティ上の脆弱性を見つけた場合は？ SECURITY.md をご覧ください。公開 issue は作成しないでください。

貢献を始める方法など、全体については SUPPORT.md をご覧ください。

開発

# Prerequisites: Go 1.26+, Docker, mise, just

# One-command setup
just setup

# Start local Pi-hole (http://localhost:8081, password: test)
# Port already taken? PIHOLE_DEV_PORT=8091 just dev-up
just dev-up

# Run quality checks (format + lint + test)
just check

# Run integration tests against local Pi-hole
just integration

# Build binary
just build

開発ガイドラインの詳細については、CONTRIBUTING.md をご覧ください。

Pi-hole は Pi-hole LLC の登録商標です。このプロジェクトは独立して保守されており、Pi-hole LLC との提携、承認、または後援を受けていません。

ライセンス

MIT