Homelab MCPサーバー

Python 3.12+ License: MIT

Model Context Protocolを介したAI駆動のホームラボインフラ管理

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

主な機能

SSH検出 -- あらゆるシステムからハードウェアおよびソフトウェアの包括的な情報を収集
サービスインストール -- テンプレートからJellyfin、Pi-hole、Ollama、Home Assistantなどをデプロイ
Proxmox統合 -- 完全なAPIアクセスとコミュニティスクリプトの検出
VM/コンテナのライフサイクル -- DockerおよびLXDワークロードのデプロイ、制御、削除
ネットワークマッピング -- デバイスの検出、トポロジの分析、変更の追跡
TerraformおよびAnsible -- ドリフト検出とPlaybookを備えた状態管理デプロイメント
認証情報管理 -- サーバーを一度登録すれば、認証情報を再入力することなく接続可能

クイックスタート

# 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統合ガイド

仕組み

セットアップ -- サーバーは初回実行時にSSHキーペアを生成します (~/.ssh/mcp_admin_rsa)
ホストのオンボード -- setup_mcp_adminを使用して、ターゲットシステム上に管理ユーザーを作成します
検証 -- verify_mcp_adminを使用して、パスワードなしのSSHアクセスを確認します
管理 -- ハードウェアの検出、サービスのインストール、VMの制御、ネットワークのマッピングを行います

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

認証情報管理

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

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

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

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

# Remove a credential
homelab-mcp credentials remove 192.168.1.10

認証情報は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ライセンス) を利用しています。

貢献

リポジトリをフォークする
フィーチャーブランチを作成する
新機能のテストを書く
すべてのテストがパスすることを確認する
プルリクエストを送信する

ライセンス

MITライセンス -- 詳細はLICENSEファイルを参照してください。

Homelab MCP Server

Homelab MCPサーバー

主な機能

クイックスタート

ドキュメント

仕組み

認証情報管理

MCPクライアント設定

開発

プロジェクト構造

謝辞

貢献

ライセンス

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API