Skip to main content
Glama
fukui-yuto

proxmox-lab-mcp

by fukui-yuto
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

proxmox-lab-mcp

Proxmox ホームラボ管理用 MCP サーバー。Raspberry Pi 5 (Ubuntu 24) 上で稼働し、Claude Code から HTTP/SSE で接続する。

構成

Claude Code (Windows)
    │  HTTP/SSE  http://192.168.210.55:8000/sse
    ▼
Raspberry Pi 5 (Ubuntu 24) ← MCP Server
    ├── proxmoxer  → Proxmox API (LAN)
    ├── terraform CLI (ネイティブ実行)
    ├── ansible CLI (ネイティブ実行)
    ├── kubectl (kubeconfig)
    └── ArgoCD REST API (http://argocd.homelab.local)

Related MCP server: homelab-mcp

セットアップ（Raspberry Pi 上）

1. uv のインストール

curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env

2. リポジトリの配置

git clone https://github.com/fukui-yuto/proxmox-lab-mcp.git ~/proxmox-lab-mcp
cd ~/proxmox-lab-mcp

3. 環境変数の設定

cp .env.example .env
vi .env  # 各サービスの接続情報を記入

必須の環境変数:

変数名

説明

PROXMOX_HOST

Proxmox ホスト IP

PROXMOX_USER

Proxmox ユーザー (例: root@pam)

PROXMOX_TOKEN_NAME

API トークン名

PROXMOX_TOKEN_VALUE

API トークン値

TERRAFORM_DIR

terraform ディレクトリのパス

ANSIBLE_DIR

ansible ディレクトリのパス

KUBECONFIG

kubeconfig ファイルのパス

ArgoCD ツールを使用する場合（任意）:

変数名

説明

ARGOCD_SERVER

ArgoCD サーバー URL (例: http://argocd.homelab.local)

ARGOCD_TOKEN

ArgoCD API トークン（expiresIn=0 で生成、パスワード変更で無効化されない）

ARGOCD_USERNAME

自動再ログイン用ユーザー名（設定すると 401 時に自動復旧）

ARGOCD_PASSWORD

自動再ログイン用パスワード（設定すると 401 時に自動復旧）

ARGOCD_VERIFY_SSL

SSL 検証 (true/false、デフォルト: false)

自動再ログインの仕組み: ARGOCD_TOKEN が期限切れ・無効になった場合、ARGOCD_USERNAME / ARGOCD_PASSWORD が設定されていれば自動でセッションを再取得してリトライする。両方設定しておくことを推奨。

ArgoCD API トークンの取得方法:

# admin アカウントに apiKey 権限を付与（初回のみ）
kubectl -n argocd patch configmap argocd-cm \
  -p '{"data": {"accounts.admin": "apiKey,login"}}'

# セッショントークンを取得してから永続 API トークンを生成
SESSION=$(curl -sk -X POST http://argocd.homelab.local/api/v1/session \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"<password>"}' | python3 -c "import sys,json; print(json.load(sys.stdin)['token'])")

curl -sk -X POST http://argocd.homelab.local/api/v1/account/admin/token \
  -H "Authorization: Bearer $SESSION" \
  -H 'Content-Type: application/json' \
  -d '{"expiresIn": 0, "id": "mcp-token"}' | python3 -c "import sys,json; print(json.load(sys.stdin)['token'])"

取得したトークンを .env の ARGOCD_TOKEN に設定し、サービスを再起動する:

# .env を編集して ARGOCD_TOKEN を更新
vi /root/proxmox-lab-mcp/.env

# MCP サービスを再起動
sudo systemctl restart proxmox-lab-mcp

また、Pi の /etc/hosts に ArgoCD のホスト名を追加しておく必要があります:

echo "192.168.210.21 argocd.homelab.local" >> /etc/hosts

4. 起動確認

uv run lab-mcp
# → http://0.0.0.0:8000/sse で起動

5. systemd サービス登録（常時起動）

sudo tee /etc/systemd/system/proxmox-lab-mcp.service > /dev/null <<EOF
[Unit]
Description=Proxmox Lab MCP Server
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/root/proxmox-lab-mcp
ExecStart=/root/.local/bin/uv run lab-mcp
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now proxmox-lab-mcp
sudo systemctl status proxmox-lab-mcp

Proxmox API トークン作成

Proxmox Web UI → Datacenter → Permissions → API Tokens で作成:

  • User: root@pam

  • Token ID: mcp-token

  • Privilege Separation: OFF（root 権限を継承）

Claude Code への登録

claude mcp add --transport sse -s user proxmox-lab http://<pi-ip>:8000/sse

利用可能なツール

Phase 1: Proxmox 読み取り系 ✅

ツール名

説明

proxmox_list_nodes

ノード一覧・CPU/メモリ/稼働状態

proxmox_list_vms

全ノードの VM/LXC 一覧

proxmox_get_vm_status

特定 VM の詳細状態

proxmox_get_node_resources

ノードのリソース使用量

proxmox_list_storage

ストレージプール一覧・使用量

Proxmox 操作系 ✅

ツール名

説明

破壊的

proxmox_start_vm

VM / LXC 起動

✗

proxmox_stop_vm

VM / LXC 停止

✓ confirm 必須

proxmox_reboot_vm

VM / LXC 再起動

✓ confirm 必須

proxmox_list_snapshots

スナップショット一覧

✗

proxmox_create_snapshot

スナップショット作成

✗

proxmox_rollback_snapshot

スナップショットへロールバック

✓ confirm 必須

proxmox_list_tasks

直近タスク一覧

✗

Proxmox 調査系 ✅

ツール名

説明

proxmox_get_vm_config

VM / LXC の設定詳細（CPU / メモリ / ディスク / ネットワーク）

proxmox_get_task_log

タスク UPID のログ取得（list_tasks で得た UPID を指定）

proxmox_get_cluster_status

クラスター全体の健全性ステータス

proxmox_list_networks

ノードのネットワーク設定一覧

proxmox_get_storage_content

ストレージ内の ISO / テンプレート一覧

proxmox_get_replication_status

ZFS レプリケーションジョブの状態（node01 ↔ node02 同期確認）

proxmox_get_backup_jobs

vzdump バックアップタスク履歴

proxmox_get_certificate_info

TLS 証明書情報と残り有効日数

Phase 2: Terraform tools ✅

ツール名

説明

破壊的

terraform_plan

terraform plan 実行・差分表示

✗

terraform_validate

構文検証のみ（apply なし）

✗

terraform_state_list

state 内リソース一覧

✗

terraform_state_show

特定リソースの state 詳細

✗

terraform_output

output 値取得

✗

terraform_apply

terraform apply 実行

✓ confirm 必須

terraform_destroy

terraform destroy 実行

✓ confirm 必須

Phase 3: Ansible tools ✅

ツール名

説明

破壊的

ansible_ping

全ホスト疎通確認

✗

ansible_list_inventory

インベントリ構成確認

✗

ansible_run_module

アドホックモジュール実行（shell, setup 等）

✗

ansible_get_facts

ホストの facts 収集（OS / ハードウェア情報）

✗

ansible_run_playbook

playbook 実行

✓ confirm 必須

Phase 4: kubectl / Helm tools ✅

ツール名

説明

破壊的

kubectl_get

kubectl get <resource>（label_selector / output / jq_filter 引数対応）

✗

kubectl_describe

kubectl describe <resource> <name>

✗

kubectl_logs

Pod ログ取得（--previous / container / since 引数対応）

✗

kubectl_exec

Pod 内コマンド実行（シェル調査・疎通確認等）

✗

kubectl_get_events

Namespace / Pod のイベント一覧（障害原因特定）

✗

kubectl_get_secret

Secret 内容確認（値はマスク表示）

✗

kubectl_get_configmap

ConfigMap 内容確認

✗

kubectl_run

一時 Pod でコマンド実行（Pod は自動削除）

✗

kubectl_port_forward

ローカルへのポートフォワード（バックグラウンド実行）

✗

kubectl_apply

マニフェスト apply（ファイルパス or インライン YAML 対応）

✓ confirm 必須

kubectl_delete

リソース削除

✓ confirm 必須

kubectl_patch

リソース部分更新（merge / strategic / json パッチ対応）

✗

kubectl_annotate

アノテーション追加・更新

✗

kubectl_rollout_status

Deployment ロールアウト状態確認

✗

kubectl_rollout_restart

Deployment / StatefulSet / DaemonSet のローリングリスタート

✗

kubectl_wait

リソースが指定条件になるまで待機（condition / timeout 指定可）

✗

kubectl_top

Node / Pod リソース使用量

✗

helm_list

Helm リリース一覧

✗

helm_get_values

リリースの values 確認

✗

helm_show_values

チャートのデフォルト values 確認（インストール前の設定確認に有用）

✗

helm_upgrade

リリースのアップグレード／インストール

✓ confirm 必須

helm_uninstall

リリースの削除

✓ confirm 必須

Phase 5: ArgoCD tools ✅

環境変数 ARGOCD_SERVER / ARGOCD_TOKEN が必要。

ツール名

説明

破壊的

argocd_list_apps

全アプリの一覧と sync/health 状態

✗

argocd_get_app

アプリ詳細（リソース一覧・条件付き状態）

✗

argocd_sync

アプリの sync 実行（revision / prune / dry_run 対応）

✓

argocd_refresh

hard refresh トリガー（Git から再取得）

✗

argocd_app_history

sync 履歴（いつ・どのリビジョンがデプロイされたか）

✗

argocd_app_managed_resources

管理リソース一覧（status / health / prune 状態）

✗

argocd_app_diff

リソース差分（live vs desired）— OutOfSync 原因特定

✗

argocd_app_terminate_op

実行中オペレーションの終了（sync 詰まり解消）

✗

argocd_list_out_of_sync

OutOfSync アプリの一覧

✗

argocd_list_unhealthy

Unhealthy アプリの一覧

✗

Longhorn / Cilium / Vault ✅

ツール名

説明

破壊的

longhorn_volumes

ボリューム一覧と状態（attached / detached / faulted）

✗

cilium_status

Cilium CNI の状態（agent health / endpoint 数）

✗

vault_status

Vault の状態（sealed / unsealed / HA モード）

✗

Velero (バックアップ / リストア) ✅

ツール名

説明

破壊的

velero_backup_list

バックアップ一覧と状態

✗

velero_restore_list

リストア一覧と状態

✗

velero_schedule_list

スケジュール一覧

✗

velero_create_backup

バックアップ作成

✓ confirm 必須

velero_create_restore

リストア実行

✓ confirm 必須

kubectl / Helm 追加 ✅

ツール名

説明

破壊的

kubectl_drain

ノードからワークロード退避（メンテナンス用）

✓ confirm 必須

kubectl_cordon

ノードをスケジュール不可にする

✗

kubectl_uncordon

ノードのスケジュール再開

✗

kubectl_scale

レプリカ数変更

✗

helm_history

リリースの履歴（リビジョン一覧）

✗

helm_rollback

リリースを指定リビジョンに戻す

✓ confirm 必須

Proxmox 追加 ✅

ツール名

説明

破壊的

proxmox_migrate_vm

VM / LXC を別ノードにマイグレーション

✓ confirm 必須

Lab ユーティリティ ✅

ツール名

説明

破壊的

lab_ping

Raspberry Pi から疎通確認

✗

lab_wakeup

Wake-on-LAN でホスト起動

✗

lab_exec

SSH 経由で VM / ホスト上のコマンドを直接実行

✗

lab_check_port

ポート開閉・疎通の確認

✗

lab_check_ports

複数ポート一括確認

✗

lab_dns_lookup

DNS 名前解決（Pi-hole 経由確認等）

✗

lab_traceroute

ネットワーク経路確認

✗

lab_curl

HTTP リクエスト実行（ヘルスチェック等）

✗

lab_journal

SSH 経由で journalctl ログ取得

✗

lab_start_cluster

クラスター全体の起動

✗

lab_stop_cluster

クラスター全体の停止

✓ confirm 必須

lab_cluster_health

ラボ全体の健全性サマリー

✗

安全設計

破壊的操作には confirm: bool パラメータを必須化：

@mcp.tool()
def terraform_apply(confirm: bool = False) -> str:
    if not confirm:
        return "ERROR: confirm=true を明示してください"
    # 実行

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • mcp-proxmox

    antonio-mello-ai
    A
    license
    A
    quality
    B
    maintenance
    MCP server for managing Proxmox VE clusters — provision VMs and containers, manage snapshots and backups, execute commands, browse storage, and monitor resources through natural language
    34
    16
    MIT

  • mcp-homelab

    asvarnon
    A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that gives AI assistants real-time access to your homelab infrastructure. It enables querying node status, managing Docker containers, controlling Proxmox VMs, and inspecting OPNsense firewall state through natural conversation.
    2
    MIT