## 🚀 Homelab MCP Servers
Model Context Protocol (MCP) サーバーを使用して、Claude Desktop 経由でホームラボインフラストラクチャを管理します。
Model Context Protocol (MCP) サーバーのコレクションで、Claude Desktop 経由でホームラボインフラストラクチャを管理および監視できます。
## 🚀 クイックスタート
### 1. リポジトリをクローンする
```bash
git clone https://github.com/bjeans/homelab-mcp
cd homelab-mcp
2. セキュリティチェックをインストールする(推奨)
python helpers/install_git_hook.py
3. 設定ファイルをセットアップする
環境変数:
copy .env.example .env
cp .env.example .env
.env を実際の値で編集します。
notepad .env
nano .env
Ansible インベントリ(使用する場合):
copy ansible_hosts.example.yml ansible_hosts.yml
cp ansible_hosts.example.yml ansible_hosts.yml
インフラストラクチャの詳細で編集します。
プロジェクトの指示:
copy PROJECT_INSTRUCTIONS.example.md PROJECT_INSTRUCTIONS.md
cp PROJECT_INSTRUCTIONS.example.md PROJECT_INSTRUCTIONS.md
ネットワークトポロジとサーバーでカスタマイズします。
AI 開発ガイドのカスタマイズ(オプション):
copy CLAUDE_CUSTOM.example.md CLAUDE_CUSTOM.md
cp CLAUDE_CUSTOM.example.md CLAUDE_CUSTOM.md
実際のサーバー名とインフラストラクチャの詳細でカスタマイズします。このファイルは gitignore されており、Claude が特定のホームラボ設定を理解できるようになります。詳細については CLAUDE.md を参照してください。
4. Python の依存関係をインストールする
pip install -r requirements.txt
5. Claude Desktop の設定に追加する
設定ファイルの場所:
- Windows:
%APPDATA%\Claude\claude_desktop_config.json
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Linux:
~/.config/Claude/claude_desktop_config.json
オプション A: 統合サーバー(推奨)
すべてのホームラボサーバーの単一エントリ:
{
"mcpServers": {
"homelab-unified": {
"command": "python",
"args": ["C:\\Path\\To\\Homelab-MCP\\homelab_unified_mcp.py"],
"env": {
"ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
}
}
}
}
注: 統合サーバーには 7 つの MCP サーバーが含まれています: Ansible、Docker、Ping、Ollama、Pi-hole、Unifi、UPS。非推奨の mcp-registry-inspector は含まれていません。
オプション B: 個別サーバー(旧バージョン、完全にサポートされています)
各サーバーの個別エントリ:
{
"mcpServers": {
"docker": {
"command": "python",
"args": ["C:\\Path\\To\\Homelab-MCP\\docker_mcp_podman.py"],
"env": {
"ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
}
},
"ollama": {
"command": "python",
"args": ["C:\\Path\\To\\Homelab-MCP\\ollama_mcp.py"],
"env": {
"ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
}
},
"pihole": {
"command": "python",
"args": ["C:\\Path\\To\\Homelab-MCP\\pihole_mcp.py"],
"env": {
"ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
}
},
"unifi": {
"command": "python",
"args": ["C:\\Path\\To\\Homelab-MCP\\unifi_mcp_optimized.py"],
"env": {
"ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
}
},
"ping": {
"command": "python",
"args": ["C:\\Path\\To\\Homelab-MCP\\ping_mcp_server.py"],
"env": {
"ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
}
},
"ups-monitor": {
"command": "python",
"args": ["C:\\Path\\To\\Homelab-MCP\\ups_mcp_server.py"],
"env": {
"ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
}
}
}
}
注: モードによってツール名が異なります。詳細については MIGRATION.md を参照してください。非推奨の mcp-registry-inspector はこの例から削除されています。Ansible MCP サーバーの統合は #39 で追跡されています。
6. Claude Desktop を再起動する
7. プロジェクトの指示を Claude に追加する
- カスタマイズした
PROJECT_INSTRUCTIONS.md の内容をコピーします。
- Claude プロジェクトの「プロジェクトの指示」フィールドに貼り付けます。
- これにより、Claude は MCP の機能に関する包括的なコンテキストを取得します。
✨ 主な機能
- Model Context Protocol (MCP) サーバーを使用して、Claude Desktop 経由でホームラボインフラストラクチャを管理および監視します。
- 複数の MCP サーバーを統合または個別に実行することができます。
- セキュリティチェックを自動化し、機密データの誤暴露を防止します。
- Ansible インベントリを使用して、ツールのパラメータを自動的に設定します。
- Docker コンテナで実行することができ、配布、分離、本番環境でのデプロイが容易です。
📦 インストール
ネイティブ Python インストール(開発および旧バージョン用)
Python の依存関係を直接インストールし、ソースからサーバーを実行します。
pip install -r requirements.txt
python homelab_unified_mcp.py
利点:
- ソースコードに完全にアクセスできます。
- デバッグと開発が容易です。
- 統合サーバーモードと個別サーバーモードの両方をサポートしています。
- 任意の Python 互換プラットフォームで実行できます。
要件:
- Python 3.10 以上と pip
- 手動での依存関係管理
.env ファイルを使用した環境設定
Docker コンテナ(本番環境用に推奨)
Docker Hub に事前に構築されたイメージが用意されており、すぐにデプロイできます。
docker pull bjeans/homelab-mcp:latest
docker-compose up -d
利点:
- Python 環境の設定が不要です。
- 事前に構築され、テストされたイメージが使用できます。
- イメージのプルによる自動更新が可能です。
- マルチプラットフォームサポート(amd64、arm64)
- 設定が簡素化されています。
- 本番環境向けのコンテナ化が可能です。
制限事項:
- 統合サーバーモードのみです。
- mcp-registry-inspector は使用できません(非推奨)。
💻 使用例
基本的な使用法
高度な使用法
📚 ドキュメント
このプロジェクトには、異なる対象読者向けのいくつかのドキュメントファイルが含まれています。
- README.md (このファイル) - インストール、セットアップ、および使用ガイド
- MIGRATION.md - v2.0 統合サーバーへの移行ガイド
- PROJECT_INSTRUCTIONS.md - AI コンテキスト用に Claude プロジェクトの指示にコピーする
- CLAUDE.md - AI アシスタントとコントリビューター向けの開発ガイド
- SECURITY.md - セキュリティポリシーとベストプラクティス
- CONTRIBUTING.md - このプロジェクトへのコントリビュート方法
- CHANGELOG.md - バージョン履歴と変更点
👥 エンドユーザー向け: この README を参照し、PROJECT_INSTRUCTIONS.md を Claude にコピーします。
🔄 v1.x からの移行の場合: 統合サーバーへの移行については MIGRATION.md を参照してください。
🤖 AI アシスタント向け: 完全な開発コンテキストについては CLAUDE.md を読んでください。
🔧 コントリビューター向け: CONTRIBUTING.md と CLAUDE.md から始めてください。
🔧 技術詳細
自動セキュリティチェック
このプロジェクトには、機密データの誤暴露を防止するための自動セキュリティ検証が含まれています。
python helpers/install_git_hook.py
これにより、すべての git push の前に helpers/pre_publish_check.py が自動的に実行され、潜在的なシークレットや機密データを含むプッシュがブロックされます。
重要なセキュリティ慣行
設定ファイル:
- ✅ 必ず
.env.example をテンプレートとして使用します。
- ✅ 必ず
.env ファイルのパーミッションを制限します(Linux/Mac では chmod 600)。
- ❌ 決して
.env をバージョン管理にコミットしないでください。
- ❌ 決して 実際のインフラストラクチャを含む
ansible_hosts.yml をコミットしないでください。
- ❌ 決して 実際のネットワークトポロジを含む
PROJECT_INSTRUCTIONS.md をコミットしないでください。
API セキュリティ:
- ✅ 必ず 各サービスに一意の API キーを使用します。
- ✅ 必ず API キーを定期的にローテーションします(90 日ごとが推奨)。
- ✅ 必ず 強力でランダムに生成されたキー(32 文字以上)を使用します。
- ❌ 決して Docker/Podman API をインターネットに公開しないでください。
- ❌ 決して 環境間で API キーを再利用しないでください。
ネットワークセキュリティ:
- ✅ 必ず ファイアウォールルールを使用して API アクセスを制限します。
- ✅ 必ず VLAN セグメンテーションを実装します。
- ✅ 可能な場合は TLS/HTTPS を有効にします。
- ❌ 決して 管理インターフェイスを公開しないでください。
詳細なセキュリティガイダンスについては SECURITY.md を参照してください。
🔒 セキュリティ通知
⚠️ 重要: このプロジェクトをデプロイする前に SECURITY.md を読んでください。
このプロジェクトは、重要なインフラストラクチャ(Docker API、DNS、ネットワークデバイス)とやり取りします。不適切な設定は、ホームラボをセキュリティリスクにさらす可能性があります。
主要なセキュリティ要件:
- 決して Docker/Podman API をインターネットに公開しないでください - ファイアウォールルールを使用してアクセスを制限します。
- .env ファイルを安全に保管してください - API キーが含まれており、決してコミットしないでください。
- 一意の API キーを使用してください - 各サービスに個別のキーを生成します。
- ネットワークセキュリティを確認してください - 適切な VLAN セグメンテーションとファイアウォールルールを確保します。
包括的なセキュリティガイダンスについては SECURITY.md を参照してください。
🐳 Docker デプロイメント(代替案)
MCP サーバーを Docker コンテナで実行することで、配布、分離、本番環境でのデプロイが容易になります。
Docker Hub: bjeans/homelab-mcp
Docker Hub を使用したクイックスタート(最も簡単)
事前に構築されたイメージは、マルチプラットフォームサポート(amd64/arm64)で自動的に Docker Hub に公開されます。
docker pull bjeans/homelab-mcp:latest
docker run -d \
--name homelab-mcp \
--network host \
-v $(pwd)/ansible_hosts.yml:/config/ansible_hosts.yml:ro \
bjeans/homelab-mcp:latest
docker pull bjeans/homelab-mcp:main-17bae01
Docker Hub で利用可能なタグ: https://hub.docker.com/r/bjeans/homelab-mcp/tags
現在利用可能なタグ:
latest - メインブランチからの最新の安定リリース(推奨)
edge - メインブランチからの最新の開発ビルド
main-<git-sha> - トレーサビリティのための特定のコミットビルド(例: main-17bae01)
セマンティックバージョンタグ(リリース後に利用可能):
2.2.0, 2.2, 2 のようなバージョンタグは、v2.2.0 Git リリースが公開されたときに作成されます。
- それまでは、最新の安定ビルドには
latest を使用してください。
マルチプラットフォームサポート:
linux/amd64 - x86_64 サーバーとワークステーション
linux/arm64 - Raspberry Pi、ARM ベースのシステム
ソースからビルドする(上級者向け)
カスタマイズが必要な場合は、イメージをローカルでビルドします。
docker pull bjeans/homelab-mcp:latest
docker-compose up -d
docker run -d \
--name homelab-mcp \
--network host \
-v $(pwd)/ansible_hosts.yml:/config/ansible_hosts.yml:ro \
bjeans/homelab-mcp:latest
ソースからビルドする(オプション):
git clone https://github.com/bjeans/homelab-mcp
cd homelab-mcp
docker build -t homelab-mcp:latest .
Docker の機能
2.0.0 Docker の改善点:
- ✅ デフォルトのエントリポイントとして統合 MCP サーバー(1 つのコンテナ内にすべての 7 つのサーバー)
- ✅ 自動統合モード検出(ENABLED_SERVERS は不要)
- ✅ 組み込みのヘルスチェック(HEALTHCHECK が構成されている)
- ✅ 非ルートユーザーセキュリティ(mcpuser UID 1000)
- ✅ 適切なシグナルハンドリングとクリーンなシャットダウン
- ✅ 高速な再構築のための最適化されたレイヤーキャッシュ
- ✅ システム依存関係が含まれている(クロスプラットフォームサポートのための iputils-ping)
設定方法
方法 1: Ansible インベントリ(推奨)
docker run -d \
--name homelab-mcp \
--network host \
-v $(pwd)/ansible_hosts.yml:/config/ansible_hosts.yml:ro \
bjeans/homelab-mcp:latest
方法 2: 環境変数(マーケットプレイス対応)
docker run -d \
--name homelab-mcp \
--network host \
-e DOCKER_SERVER1_ENDPOINT=192.168.1.100:2375 \
-e DOCKER_SERVER1_NAME=Local-Docker \
-e OLLAMA_SERVER1_ENDPOINT=192.168.1.100:11434 \
bjeans/homelab-mcp:latest
旧モード: 個別サーバー(Docker)
下位互換性のために、ENABLED_SERVERS を設定することで個別サーバーを実行することもできます。
docker run -d \
--name homelab-mcp-docker \
--network host \
-e ENABLED_SERVERS=docker \
-v $(pwd)/ansible_hosts.yml:/config/ansible_hosts.yml:ro \
bjeans/homelab-mcp:latest
利用可能なサーバー
統合モード(デフォルト):
- ✅ 1 つのプロセスですべての 7 つのサーバー: Ansible、Docker、Ping、Ollama、Pi-hole、Unifi、UPS
- ✅ 名前空間付きのツール(例:
ansible_get_all_hosts, docker_get_containers, ups_get_ups_status)
- ✅ 単一の設定エントリ
- ✅ 組み込みのヘルスチェック
旧モード(ENABLED_SERVERS を設定):
- ✅
ansible - Ansible インベントリクエリ
- ✅
docker - Docker/Podman コンテナ管理
- ✅
ping - ネットワーク ping ユーティリティ
- ✅
ollama - Ollama AI モデル管理
- ✅
pihole - Pi-hole DNS 統計
- ✅
unifi - Unifi ネットワークデバイス監視
- ✅
ups - UPS/NUT 電源監視
Docker 設定
2 つの設定方法がサポートされています。
- Ansible インベントリ(推奨) - ボリュームとしてマウントする
- 環境変数 - Docker
-e フラグを使用して渡す
包括的な Docker デプロイメントガイドについては DOCKER.md を参照してください。これには、詳細なセットアップ手順、ネットワーク構成オプション、セキュリティベストプラクティス、Claude Desktop との統合、一般的な問題のトラブルシューティングが含まれます。
Claude Desktop との統合
統合モード(推奨):
{
"mcpServers": {
"homelab-unified": {
"command": "docker",
"args": ["exec", "-i", "homelab-mcp", "python", "homelab_unified_mcp.py"]
}
}
}
旧モード(個別サーバー):
{
"mcpServers": {
"homelab-docker": {
"command": "docker",
"args": ["exec", "-i", "homelab-mcp-docker", "python", "docker_mcp_podman.py"]
},
"homelab-ping": {
"command": "docker",
"args": ["exec", "-i", "homelab-mcp", "python", "ping_mcp_server.py"]
}
}
}
重要: 適切な MCP stdio 通信のために docker exec -i(-it ではなく)を使用してください。
Docker コンテナのテスト
クイックバリデーションテスト(環境変数を使用 - マーケットプレイス対応):
docker run --rm --network host \
-e DOCKER_SERVER1_ENDPOINT=localhost:2375 \
-e OLLAMA_SERVER1_ENDPOINT=localhost:11434 \
bjeans/homelab-mcp:latest
docker run --rm --network host \
-e ENABLED_SERVERS=ping \
bjeans/homelab-mcp:latest
Docker Compose のテスト:
docker-compose up -d
docker-compose logs -f
包括的な Docker デプロイメントガイドについては DOCKER.md を参照してください。
📦 利用可能な MCP サーバー
✨ 動的ツールパラメータ列挙型(v2.1.0 の新機能)
Ansible インベントリを設定すると、Claude Desktop は自動的にインフラストラクチャのオプションをドロップダウンメニューに表示します。ホスト名やグループ名を推測する必要はありません!
自動的に入力される項目:
- Ping ツール - Ansible グループがドロップダウンメニューに表示されます。
- Docker ツール - Docker/Podman ホストがドロップダウンに表示されます。
- Ollama ツール - Ollama サーバーのホスト名が選択可能になります。
- UPS ツール - NUT サーバーのホスト名がドロップダウンに表示されます。
動作方法:
.env ファイルに ANSIBLE_INVENTORY_PATH を設定します。
- Claude Desktop を再起動します(必須 - 列挙型は起動時に読み込まれます)。
- ツールを使用するとき、Claude は手動入力ではなく実際のインフラストラクチャをドロップダウンメニューに表示します。
重要な注意事項:
- 再起動が必要: Ansible インベントリの変更は、ドロップダウンオプションを更新するために Claude Desktop を再起動する必要があります。
- パフォーマンス: 列挙型は起動時に 1 回生成されるため、大規模なインベントリ(100 以上のホスト)でも影響は最小限です。
- 緩やかな劣化: Ansible インベントリが構成されていない場合でも、ツールは機能します - ただし、ドロップダウンの提案は表示されません。
例(変更前/変更後):
変更前: "どのグループを ping しますか?" → ユーザーが手動で "webservers" を入力する(または推測する)
変更後: "どのグループを ping しますか?" → ユーザーがドロップダウンから選択する: all, docker_hosts, webservers, databases, など。
トラブルシューティング:
- ドロップダウンが表示されない場合:
ANSIBLE_INVENTORY_PATH が設定されていることを確認し、Claude Desktop を再起動します。
- 間違ったオプションが表示される場合: Ansible インベントリが最新であることを確認し、Claude Desktop を再起動します。
- パフォーマンスの問題がある場合: 列挙型の生成は起動時に 1 回行われます - 遅い場合は、インベントリファイルのサイズと Ansible のインストールを確認してください。
MCP レジストリインスペクター(⚠️ 非推奨)
非推奨通知 (v2.3.0): このツールは非推奨です。Claude Desktop は現在、ネイティブのファイルシステムアクセスを持っているため、この MCP サーバーは不要です。Claude に直接 MCP サーバーのファイルや設定を読み取らせることができます。
代替策: Claude の組み込みファイルアクセスを使用します。
- "claude_desktop_config.json ファイルを読んでください"
- "docker_mcp_podman.py のソースコードを表示してください"
- "このディレクトリ内のすべての .py ファイルをリストしてください"
既存の設定を持つユーザー向け: このサーバーは引き続き動作しますが、更新は行われません。v3.0.0 ではドキュメントから削除されます。claude_desktop_config.json から削除することを検討してください。
旧バージョンの設定(参考用のみ)
ツール:
get_claude_config - Claude Desktop MCP 設定を表示する
list_mcp_servers - すべての登録された MCP サーバーをリストする
list_mcp_directory - MCP 開発ディレクトリを参照する
read_mcp_file - MCP サーバーのソースコードを読む
write_mcp_file - MCP サーバーのファイルを書き込む/更新する
search_mcp_files - 名前でファイルを検索する
設定:
MCP_DIRECTORY=/path/to/your/Homelab-MCP
CLAUDE_CONFIG_PATH=/path/to/claude_desktop_config.json
Docker/Podman コンテナマネージャー
複数のホストにまたがる Docker および Podman コンテナを管理します。
🔒 セキュリティ警告: Docker/Podman API は通常、認証なしの暗号化されていない HTTP を使用します。必要なファイアウォール構成については SECURITY.md を参照してください。
ツール:
個別サーバーモード:
get_docker_containers - 特定のホスト上のコンテナを取得する
get_all_containers - すべてのホスト上のすべてのコンテナを取得する
get_container_stats - CPU とメモリの統計を取得する
check_container - 特定のコンテナが実行中かどうかを確認する
find_containers_by_label - ラベルでコンテナを検索する
get_container_labels - コンテナのすべてのラベルを取得する
統合サーバーモード(名前空間付き):
docker_get_containers - 特定のホスト上のコンテナを取得する
docker_get_all_containers - すべてのホスト上のすべてのコンテナを取得する
docker_get_container_stats - CPU とメモリの統計を取得する
docker_check_container - 特定のコンテナが実行中かどうかを確認する
docker_find_containers_by_label - ラベルでコンテナを検索する
docker_get_container_labels - コンテナのすべてのラベルを取得する
設定オプション:
オプション 1: Ansible インベントリを使用する(推奨)
ANSIBLE_INVENTORY_PATH=/path/to/ansible_hosts.yml
DOCKER_ANSIBLE_GROUP=docker_hosts
PODMAN_ANSIBLE_GROUP=podman_hosts
オプション 2: 環境変数を使用する
DOCKER_SERVER1_ENDPOINT=192.168.1.100:2375
DOCKER_SERVER2_ENDPOINT=192.168.1.101:2375
PODMAN_SERVER1_ENDPOINT=192.168.1.102:8080
Ollama AI モデルマネージャー
ホームラボ全体の Ollama AI モデルインスタンスを監視および管理し、統一 API アクセスのための LiteLLM プロキシを確認します。
含まれる内容
Ollama 監視:
- 異なるホストにまたがる複数の Ollama インスタンスを追跡します。
- 利用可能なモデルとそのサイズを表示します。
- インスタンスのヘルスと可用性を確認します。
LiteLLM プロキシ統合:
- LiteLLM は、すべての Ollama インスタンスにわたって統一された OpenAI 互換 API を提供します。
- 複数の Ollama サーバー間での負荷分散とフェイルオーバーを可能にします。
- ローカルモデルで OpenAI クライアントライブラリを使用できるようにします。
- MCP サーバーは、LiteLLM プロキシがオンラインで応答していることを確認できます。
LiteLLM を使用する理由:
- 負荷分散: 複数の Ollama インスタンスに自動的にリクエストを分散します。
- フェイルオーバー: 1 つの Ollama サーバーがダウンした場合、リクエストは正常なサーバーにルーティングされます。
- OpenAI 互換性: ローカルモデルで任意の OpenAI SDK/ライブラリを使用できます。
- 集中アクセス: すべてのモデルに対する単一のエンドポイント(例:
http://192.0.2.10:4000)。
- 使用状況追跡: どのモデルが最も多く使用されているかを監視します。
ツール:
get_ollama_status - すべての Ollama インスタンスのステータスとモデル数を確認する
get_ollama_models - 特定のホストの詳細なモデルリストを取得する
get_litellm_status - LiteLLM プロキシがオンラインで応答していることを確認する
設定オプション:
オプション 1: Ansible インベントリを使用する(推奨)
ANSIBLE_INVENTORY_PATH=/path/to/ansible_hosts.yml
OLLAMA_PORT=11434
OLLAMA_INVENTORY_GROUP=ollama_servers
LITELLM_HOST=192.168.1.100
LITELLM_PORT=4000
オプション 2: 環境変数を使用する
OLLAMA_SERVER1=192.168.1.100
OLLAMA_SERVER2=192.168.1.101
OLLAMA_WORKSTATION=192.168.1.150
LITELLM_HOST=192.168.1.100
LITELLM_PORT=4000
LiteLLM のセットアップ(オプション):
LiteLLM を使用して Ollama インスタンスに統一アクセスする場合は、以下の手順を実行します。
- LiteLLM をサーバーの 1 つにインストールします。
pip install litellm[proxy]
- 設定ファイル (
litellm_config.yaml) を作成します。
model_list:
- model_name: llama3.2
litellm_params:
model: ollama/llama3.2
api_base: http://server1:11434
- model_name: llama3.2
litellm_params:
model: ollama/llama3.2
api_base: http://server2:11434
router_settings:
routing_strategy: usage-based-routing
- LiteLLM プロキシを起動します。
litellm --config litellm_config.yaml --port 4000
- MCP ツールを使用して、プロキシが実行中であることを確認します。
- Claude で: "LiteLLM プロキシのステータスを確認してください"
使用例:
- "実行中の Ollama インスタンスはどれですか?"
- "Dell-Server 上のすべてのモデルを表示してください"
- "LiteLLM プロキシはオンラインですか?"
- "すべてのサーバーで利用可能なモデルはいくつですか?"
Pi-hole DNS マネージャー
Pi-hole DNS 統計とステータスを監視します。
🔒 セキュリティ注意事項: Pi-hole API キーを .env ファイルに安全に保管してください。インスタンスごとに一意のキーを生成してください。
ツール:
get_pihole_stats - すべての Pi-hole インスタンスから DNS 統計を取得する
get_pihole_status - どの Pi-hole インスタンスがオンラインかを確認する
設定オプション:
オプション 1: Ansible インベントリを使用する(推奨)
ANSIBLE_INVENTORY_PATH=/path/to/ansible_hosts.yml
PIHOLE_ANSIBLE_GROUP=PiHole
PIHOLE_API_KEY_SERVER1=your-api-key-here
PIHOLE_API_KEY_SERVER2=your-api-key-here
オプション 2: 環境変数を使用する
PIHOLE_API_KEY_SERVER1=your-api-key
PIHOLE_API_KEY_SERVER2=your-api-key
PIHOLE_SERVER1_HOST=pihole1.local
PIHOLE_SERVER1_PORT=80
PIHOLE_SERVER2_HOST=pihole2.local
PIHOLE_SERVER2_PORT=8053
Pi-hole API キーの取得方法:
- Web UI: Settings → API → Show API Token
- または新しいキーを生成する:
pihole -a -p Pi-hole サーバーで
Unifi ネットワークモニター
キャッシュを使用して Unifi ネットワークインフラストラクチャとクライアントを監視し、パフォーマンスを向上させます。
🔒 セキュリティ注意事項: 最小限の必要な権限を持つ専用の API キーを使用してください。
ツール:
get_network_devices - すべてのネットワークデバイス(スイッチ、AP、ゲートウェイ)を取得する
get_network_clients - すべてのアクティブなネットワーククライアントを取得する
get_network_summary - ネットワークの概要を取得する
refresh_network_data - コントローラーから強制的にデータを更新する(キャッシュをバイパスする)
設定:
UNIFI_API_KEY=your-unifi-api-key
UNIFI_HOST=192.168.1.1
注: データはパフォーマンス向上のために 5 分間キャッシュされます。refresh_network_data を使用して強制的に更新します。
Ansible インベントリインスペクター
Ansible インベントリ情報を照会します(読み取り専用)。統合モードとスタンドアロンモードの両方で利用可能です。
統合モードのツール (ansible_ 接頭辞付き):
ansible_get_all_hosts - インベントリ内のすべてのホストを取得する
ansible_get_all_groups - すべてのグループを取得する
ansible_get_host_details - 詳細なホスト情報を取得する
ansible_get_group_details - 詳細なグループ情報を取得する
ansible_get_hosts_by_group - 特定のグループ内のホストを取得する
ansible_search_hosts - パターンまたは変数でホストを検索する
ansible_get_inventory_summary - インベントリの概要を取得する
ansible_reload_inventory - ディスクからインベントリを再読み込みする
スタンドアロンモードのツール (接頭辞なし):
get_all_hosts - インベントリ内のすべてのホストを取得する
get_all_groups - すべてのグループを取得する
get_host_details - 詳細なホスト情報を取得する
get_group_details - 詳細なグループ情報を取得する
get_hosts_by_group - 特定のグループ内のホストを取得する
search_hosts - パターンまたは変数でホストを検索する
get_inventory_summary - インベントリの概要を取得する
reload_inventory - ディスクからインベントリを再読み込みする
設定:
ANSIBLE_INVENTORY_PATH=/path/to/ansible_hosts.yml
デプロイメント:
- ✅ 統合サーバーモードで利用可能
- ✅ Docker デプロイメントで利用可能
- ✅ スタンドアロンモードで利用可能:
python ansible_mcp_server.py
Ping ネットワーク接続モニター
ICMP ping を使用してインフラストラクチャ全体のネットワーク接続性とホストの可用性をテストします。
このツールを使用する理由:
- 停電後または電源イベント後の迅速なヘルスチェック
- サービス固有の MCP を照会する前に、どのホストが到達可能かを確認する
- ネットワーク問題を特定するための簡単なトラブルシューティングツール
- インフラストラクチャの基本的な接続性テスト
ツール:
ping_host - 名前で単一のホストを ping する(Ansible インベントリから解決)
ping_group - Ansible グループ内のすべてのホストを同時に ping する
ping_all - インフラストラクチャ全体のすべてのホストを同時に ping する
list_groups - ping 操作に使用可能な Ansible グループをリストする
機能:
- ✅ クロスプラットフォームサポート - Windows、Linux、および macOS で動作します。
- ✅ Ansible 統合 - インベントリから自動的にホスト名/IP を解決します。
- ✅ 同時 ping - 複数のホストを同時にテストして、結果を迅速に取得します。
- ✅ 詳細な統計 - RTT 最小/平均/最大、パケット損失率
- ✅ カスタマイズ可能 - タイムアウトとパケット数を構成できます。
- ✅ 依存関係なし - システムの
ping コマンドを使用します(追加のライブラリは必要ありません)。
設定:
ANSIBLE_INVENTORY_PATH=/path/to/ansible_hosts.yml
使用例:
- "server1.example.local を ping してください"
- "すべての Pi-hole サーバーへの接続性を確認してください"
- "すべての Ubuntu_Server ホストを ping してください"
- "インフラストラクチャ全体への接続性をテストしてください"
- "ping できるグループはどれですか?"
使用するタイミング:
- 停電後 - どのホストがオンラインに戻ったかを迅速に識別する
- サービスチェック前 - 特定のサービスをチェックする前に、ホストが到達可能であることを確認する
- ネットワークトラブルシューティング - 接続性の問題をサービスの問題から切り分ける
- ヘルスモニタリング - インフラストラクチャの可用性を定期的に確認する
UPS 監視(Network UPS Tools)
Network UPS Tools (NUT) プロトコルを使用して、インフラストラクチャ全体の UPS (無停電電源装置) デバイスを監視します。
このツールを使用する理由:
- 電源インフラストラクチャのステータスをリアルタイムで可視化する
- 停電時にバッテリが消耗する前に事前にアラートを発する
- 異なるホストにまたがる複数の UPS デバイスを監視する
- バッテリの健康状態とランタイム推定値を追跡する
- 重要なインフラストラクチャの計画に不可欠
ツール:
get_ups_status - すべての NUT サーバー全体のすべての UPS デバイスのステータスを確認する
get_ups_details - 特定の UPS デバイスの詳細情報を取得する
get_battery_runtime - すべての UPS デバイスのバッテリランタイム推定値を取得する
get_power_events - 最近の電源イベント(バッテリ駆動、バッテリ残量低下)を確認する
list_ups_devices - インベントリに構成されているすべての UPS デバイスをリストする
reload_inventory - 変更後に Ansible インベントリを再読み込みする
機能:
- ✅ NUT プロトコルサポート - Network UPS Tools 標準プロトコル(ポート 3493)を使用します。
- ✅ Ansible 統合 - インベントリから自動的に UPS を検出します。
- ✅ ホストごとに複数の UPS - 複数の UPS デバイスを持つサーバーをサポートします。
- ✅ バッテリ監視 - 充電レベル、残りランタイム、負荷率を追跡します。
- ✅ 電源イベント検出 - UPS がバッテリ駆動に切り替わったり、バッテリ残量が低下したりしたときを識別します。
- ✅ クロスプラットフォーム - 任意の NUT 互換 UPS(TrippLite、APC、CyberPower など)で動作します。
- ✅ 柔軟な認証 - オプションのユーザー名/パスワード認証
設定:
オプション 1: Ansible インベントリを使用する(推奨)
ANSIBLE_INVENTORY_PATH=/path/to/ansible_hosts.yml
NUT_PORT=3493
NUT_USERNAME=monuser
NUT_PASSWORD=secret
Ansible インベントリの例:
nut_servers:
hosts:
dell-server.example.local:
ansible_host: 192.168.1.100
nut_port: 3493
ups_devices:
- name: tripplite
description: "TrippLite SMART1500LCDXL"
オプション 2: 環境変数を使用する
NUT_PORT=3493
NUT_USERNAME=monuser
NUT_PASSWORD=secret
前提条件:
- UPS デバイスを持つサーバーに NUT をインストールします。
sudo apt install nut nut-client nut-server
sudo dnf install nut nut-client
- NUT デーモン (
/etc/nut/ups.conf) を構成します。
[tripplite]
driver = usbhid-ups
port = auto
desc = "TrippLite SMART1500LCDXL"
- ネットワーク監視を有効にします (
/etc/nut/upsd.conf)。
LISTEN 0.0.0.0 3493
- アクセスを構成します (
/etc/nut/upsd.users)。
[monuser]
password = secret
upsmon master
- NUT サービスを起動します。
sudo systemctl enable nut-server nut-client
sudo systemctl start nut-server nut-client
使用例:
- "すべての UPS デバイスのステータスはどうですか?"
- "Dell サーバーの UPS のバッテリランタイムを表示してください"
- "最近の電源イベントを確認してください"
- "TrippLite UPS の詳細情報を取得してください"
- "構成されているすべての UPS デバイスをリストしてください"
使用するタイミング:
- 電源の瞬断後 - UPS デバイスがイベントを適切に処理したことを確認する
- メンテナンス前 - バッテリレベルと推定ランタイムを確認する
- 定期的な監視 - UPS の健康状態とバッテリ状態を追跡する
- 容量計画 - システムがバッテリでどれだけ長く動作できるかを理解する
一般的な UPS ステータスコード:
OL - オンライン(通常動作、AC 電源あり)
OB - バッテリ駆動(停電、バッテリで動作中)
LB - バッテリ残量低下(バッテリが危険なレベルまで低下、シャットダウン間近)
CHRG - 充電中(バッテリが充電中)
RB - バッテリ交換が必要(バッテリを交換する必要があります)
📋 要件
システム要件
- Python: 3.10 以上
- Claude Desktop: 最新バージョンを推奨
- ネットワークアクセス: ホームラボサービスへの接続性