Ansible MCP Server

Homelab MCP Server

Model Context Protocol による AI を活用したホームラボインフラストラクチャ管理

AI アシスタントがホームラボインフラストラクチャを管理、デプロイ、監視できる Python MCP サーバーです。SSH による検出、VM 管理、サービスのインストール、ネットワークトポロジーのマッピング、Proxmox の操作、認証情報の管理など、幅広いツールを提供します。

主な機能

• SSH による検出 -- 任意のシステムからハードウェアとソフトウェアの包括的な情報を収集します
• サービスのインストール -- テンプレートを使用して Jellyfin、Pi-hole、Ollama、Home Assistant などをデプロイします
• Proxmox 連携 -- コミュニティスクリプトの検出に加え、API にフルアクセスできます
• VM／コンテナーのライフサイクル管理 -- Docker および LXD のワークロードをデプロイ、制御、削除します
• ネットワークマッピング -- デバイスを検出し、トポロジーを分析して、変更を追跡します
• Terraform と Ansible -- ドリフト検出とプレイブックに対応した、状態管理型のデプロイを実現します
• 認証情報の管理 -- サーバーを一度登録すれば、認証情報を再入力せずに接続できます

クイックスタート

# Install from PyPI (recommended — no clone needed)
uvx homelab-mcp

# Or clone and run from source
git clone https://github.com/washyu/homelab_mcp.git
cd homelab_mcp
uv sync && uv run python run_server.py

環境変数、MCP クライアントの設定、最初のツール呼び出しを含む詳しい手順については、セットアップガイドを参照してください。

ドキュメント

ガイド	説明
セットアップガイド	初期状態から最初のツール呼び出しまで
ツールリファレンス	引数と使用例を含むすべてのツール
設定	環境変数と CLI オプション
Claude Desktop のセットアップ	Claude Desktop 連携ガイド
HTTP サービス	REST／OpenAPI モード、エンドポイント、エラー仕様

仕組み

1. セットアップ -- 初回起動時にサーバーが SSH 鍵ペアを生成します（~/.ssh/mcp_admin_rsa）
2. ホストの登録 -- setup_mcp_admin を使用して、対象システムに管理ユーザーを作成します
3. 確認 -- verify_mcp_admin を使用して、パスワードなしの SSH アクセスを確認します
4. 管理 -- ハードウェアの検出、サービスのインストール、VM の制御、ネットワークのマッピングを行います

サーバーは MCP プロトコルを使用して stdio 経由で通信します。MCP 対応のクライアント（Claude Desktop など）に接続すれば、自然言語で操作できます。

認証情報の管理

SSH と Proxmox の認証情報を一度保存すれば、サーバーが接続のたびに自動で注入します。

# Store an SSH credential
homelab-mcp credentials add 192.168.1.10 admin

# Store an SSH key-based credential (stores the key file path in the keyring, not the key)
homelab-mcp credentials add 192.168.1.10 admin --key-path ~/.ssh/id_ed25519

# Store a Proxmox API credential
homelab-mcp credentials add 192.168.1.200 root@pam --type proxmox

# Update an existing credential — `add` is upsert; re-running replaces the stored entry
homelab-mcp credentials add 192.168.1.10 admin

# List stored credentials
homelab-mcp credentials list
homelab-mcp credentials list --type proxmox

# Remove a credential
homelab-mcp credentials remove 192.168.1.10

CLI では認証情報に対する CRUD 操作をすべて実行できます。add（作成／更新 — アップサート）、list（読み取り）、remove（削除）を使用します。個別の update サブコマンドはありません。add を再実行すると、キーリングのシークレットとレジストリエントリーの認証タイプが両方置き換わります。

認証情報は OS のキーリングに保存されます（Linux では libsecret、macOS では Keychain）。OS のキーリングを利用できない場合（ヘッドレスサーバーなど）は、認証情報は環境変数にフォールバックします。

詳しくは認証情報 CLI リファレンスを参照してください。

MCP クライアントの設定

PyPI から（uvx）— 推奨：

{
  "mcpServers": {
    "homelab": {
      "command": "uvx",
      "args": ["homelab-mcp"]
    }
  }
}

ソースをクローンして使用：

{
  "mcpServers": {
    "homelab": {
      "command": "uv",
      "args": ["run", "python", "run_server.py"],
      "cwd": "/path/to/homelab_mcp"
    }
  }
}

開発

# Install with dev dependencies
uv sync --group dev

# Run tests (unit only, no Docker required)
uv run pytest tests/ -m "not integration"

# Code quality
uv run ruff check src/ tests/
uv run mypy src/

本番環境へのデプロイの詳細については、DEPLOYMENT.mdを参照してください。

プロジェクト構成

src/homelab_mcp/
  server.py              # MCP server with JSON-RPC protocol
  tool_schemas/          # Tool definitions (8 schema files)
  tool_annotations.py    # MCP annotation hints per tool
  ssh_tools.py           # SSH discovery and hardware detection
  service_installer.py   # Service installation framework
  infrastructure_crud.py # Infrastructure lifecycle management
  vm_operations.py       # VM/container operations
  sitemap.py             # Network topology mapping
  database.py            # SQLite device tracking
  error_handling.py      # Centralized error handling
  credential_store.py    # OS keyring credential storage
  log_filter.py          # Credential redaction for log output
  prompt_registry.py     # MCP prompts registry
  resource_readers.py    # MCP resource read handlers
  service_templates/     # YAML service definitions
tests/                   # Unit and integration tests
docs/                    # Full documentation

謝辞

Proxmox コミュニティスクリプトとの連携には、community-scripts/ProxmoxVE（MIT License）を使用しています。

貢献

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. 新しい機能のテストを作成します
4. すべてのテストが通ることを確認します
5. プルリクエストを送信します

ライセンス

MIT License — 詳細については LICENSE ファイルを参照してください。