proxmox-mcp-tools

Proxmox MCP ツールリファレンス

AI エージェントスキル：Model Context Protocol を介した 92 種類の Proxmox Virtual Environment 管理ツールの完全なリファレンス

概要

このスキルでは、Model Context Protocol（MCP）を介して Proxmox VE インフラストラクチャを管理するための、包括的な 92 種類のツールを提供する @bldg-7/proxmox-mcp サーバーの使い方を学びます。

学習内容：

• MCP を介して Proxmox VE に接続する方法
• 14 の機能領域に分類された 92 種類のツール
• 権限モデル（基本操作と昇格操作）
• 一般的なワークフローとパターン
• API の特性に関するトラブルシューティング

対象読者：Proxmox インフラストラクチャの管理、VM/LXC のプロビジョニングの自動化、クラスターの健全性の監視、または運用タスクの実行を行う AI エージェント。

---

クイックスタート

接続の設定

必須の環境変数：

PROXMOX_HOST=pve.example.com
PROXMOX_TOKEN_NAME=mytoken
PROXMOX_TOKEN_VALUE=abc123-def456-ghi789

任意の設定：

PROXMOX_USER=root@pam          # Default: root@pam
PROXMOX_SSL_MODE=verify         # strict|verify|insecure (default: strict)
PROXMOX_SSL_CA_CERT=/path/ca.pem # CA cert (PEM) trusted in verify mode — required for self-signed certs
PROXMOX_ALLOW_ELEVATED=true     # Enable create/modify/delete (default: false)
PROXMOX_PORT=8006               # Default: 8006
PROXMOX_LOG_LEVEL=info          # trace|debug|info|warn|error|fatal (default: info)

SSH の設定（proxmox_lxc_exec 用）：

PROXMOX_SSH_ENABLED=true        # Enable SSH-based LXC exec (default: false)
PROXMOX_SSH_HOST=pve.example.com # SSH host (falls back to PROXMOX_HOST)
PROXMOX_SSH_PORT=22             # SSH port (default: 22)
PROXMOX_SSH_USER=root           # SSH username (default: root)
PROXMOX_SSH_KEY_PATH=~/.ssh/id_rsa # Path to SSH private key (required when SSH enabled)
PROXMOX_SSH_NODE=pve1           # Proxmox node name (required when SSH enabled)
PROXMOX_SSH_HOST_KEY_FINGERPRINT=sha256:... # Optional host key verification

権限モデル

レベル	操作	必要な環境変数
基本	読み取り専用（一覧表示、取得、ステータス）	なし
昇格 🔒	作成、変更、削除	PROXMOX_ALLOW_ELEVATED=true

合計 92 種類のツール — 読み取り操作は基本権限で実行できます。作成／変更／削除操作には昇格権限が必要です（多くのツールは混合型で、昇格の要否は action によって異なります）。

SSL モード

• strict：証明書を完全に検証します（本番環境向け）
• verify：strict と同様ですが、PROXMOX_SSL_CA_CERT の CA も信頼します。自己署名証明書の場合は設定してください。設定しない場合は strict と同じです
• insecure：検証を行いません（開発環境のみ）

---

ツールのカテゴリ

領域	ツール数	主な操作	リファレンス
ノード	47	ノードのステータス、ネットワーク設定、システム操作、コンソールアクセス	proxmox-nodes.md
QEMU VM	26	VM のライフサイクル、設定、ディスク、ネットワーク、コマンド	proxmox-vm.md
LXC コンテナー	20	コンテナーのライフサイクル、設定、マウントポイント、ネットワーク、実行	proxmox-lxc.md
VM/LXC 共通	22	エージェント、ファイアウォール、移行（どちらにも対応）	proxmox-vm-lxc-shared.md
スナップショットとバックアップ	14	スナップショットの作成／復元、バックアップジョブ	proxmox-snapshots-backups.md
ストレージ	16	ストレージ設定、コンテンツ、ファイル操作、ノードディスク	proxmox-storage.md
ネットワーキング	20	SDN（VNet、ゾーン、コントローラー、サブネット）	proxmox-networking.md
クラスター	54	HA、ファイアウォール、エイリアス、IP セット、バックアップジョブ、レプリケーション、設定	proxmox-cluster.md
アクセス制御	25	ユーザー、グループ、ロール、ACL、ドメイン、API トークン	proxmox-access-control.md
Ceph	16	Ceph OSD、MON、MDS、プール、ファイルシステム	proxmox-ceph.md
プール	5	リソースプールの管理	proxmox-pools.md
証明書	7	ノード証明書、カスタム SSL、ACME 注文	proxmox-certificates.md
ACME	8	ACME アカウント、プラグイン、ディレクトリ	proxmox-acme.md
通知	5	通知ターゲット、SMTP/Gotify のテスト	proxmox-notifications.md

合計：92 種類のツール

---

一般的なワークフロー

1. VM の作成と設定

1. proxmox_get_next_vmid → Get available VM ID
2. proxmox_create_vm → Create VM with basic config
3. proxmox_vm_disk → Attach storage
4. proxmox_guest_network → Configure network
5. proxmox_guest_start → Power on
6. proxmox_guest_status → Verify running

2. テスト用 VM のクローン作成

1. proxmox_guest_config → Review source VM
2. proxmox_guest_snapshot → Snapshot before clone
3. proxmox_guest_clone → Create clone (full or linked)
4. proxmox_guest_start → Start cloned VM

3. バックアップと復元

# Backup
1. proxmox_backup → Create backup to storage
2. proxmox_backup → Verify backup exists

# Restore
1. proxmox_backup → Find backup file
2. proxmox_backup → Restore to new/existing VM

4. ノード間での VM の移行

1. proxmox_node → List available target nodes
2. proxmox_guest_status → Check VM is running
3. proxmox_guest_migrate → Live or offline migration
4. proxmox_guest_status → Verify on new node

5. 重要な VM の HA 設定

1. proxmox_ha_group → Define node group
2. proxmox_ha_resource → Add VM to HA
3. proxmox_ha_resource → Monitor HA state

6. クラスターの健全性の監視

1. proxmox_cluster → Overall cluster state
2. proxmox_node → Node-level health
3. proxmox_node_task → Recent operations
4. proxmox_ceph → Ceph cluster (if used)

7. ストレージの管理

1. proxmox_storage_config → Available storage
2. proxmox_storage_content → Browse content
3. proxmox_storage_content → Upload ISO/template
4. proxmox_storage_content → Clean old backups

その他のワークフロー：proxmox-workflows.md を参照してください。

---

トラブルシューティングのクイックリファレンス

1. 接続拒否

症状: ECONNREFUSED またはタイムアウト
修正方法: PROXMOX_HOST を確認し、ポート 8006 とファイアウォールのルールを確認してください

2. 認証失敗

症状: 401 Unauthorized
修正方法: トークン名／値を確認し、Proxmox でトークンに権限が付与されていることを確認してください

3. SSL 証明書エラー

症状: UNABLE_TO_VERIFY_LEAF_SIGNATURE
修正方法: 自己署名証明書には PROXMOX_SSL_MODE=verify を使用してください

4. 権限拒否

症状: 🚫 Permission Denied
修正方法: 作成／変更／削除操作では PROXMOX_ALLOW_ELEVATED=true を設定してください

5. VM が見つからない（404 ではなく 500）

症状: VM が見つからない場合に API が 500 エラーを返す
修正方法: これは Proxmox API の仕様上の癖です。一部の状況では 500 を「見つからない」として扱ってください

詳細なトラブルシューティング: proxmox-troubleshooting.md を参照してください

---

ツールのレスポンス形式

すべてのツールは、構造化された MCP レスポンスを返します。

成功:

{
  "content": [{"type": "text", "text": "✅ Operation successful\n\n• Details..."}],
  "isError": false
}

エラー:

{
  "content": [{"type": "text", "text": "❌ Error: Reason..."}],
  "isError": true
}

権限拒否:

{
  "content": [{"type": "text", "text": "🚫 Permission Denied: Set PROXMOX_ALLOW_ELEVATED=true"}],
  "isError": true
}

---

参考資料

ドメイン固有のドキュメント

• proxmox-nodes.md - ノード管理、ネットワーク設定、システム操作（47 個のツール）
• proxmox-vm.md - QEMU VM 操作（26 個のツール）
• proxmox-lxc.md - LXC コンテナー操作（20 個のツール）
• proxmox-vm-lxc-shared.md - VM／LXC 共通操作（22 個のツール）
• proxmox-snapshots-backups.md - スナップショットとバックアップ（14 個のツール）
• proxmox-storage.md - ストレージ管理（16 個のツール）
• proxmox-networking.md - SDN 設定（20 個のツール）
• proxmox-cluster.md - クラスター操作（54 個のツール）
• proxmox-access-control.md - ユーザー、ロール、ACL、API トークン（25 個のツール）
• proxmox-ceph.md - Ceph ストレージクラスター（16 個のツール）
• proxmox-pools.md - リソースプール（5 個のツール）
• proxmox-certificates.md - 証明書管理（7 個のツール）
• proxmox-acme.md - ACME アカウントとプラグインの管理（8 個のツール）
• proxmox-notifications.md - 通知先（5 個のツール）

運用ガイド

• proxmox-workflows.md - 一般的な運用パターン
• proxmox-troubleshooting.md - API の仕様上の癖と解決策

---

使用上のヒント

1. 権限を必ず確認する: まず基本的なツールを使用し、必要な場合にのみ昇格を有効にしてください
2. 破壊的な操作の前に確認する: delete_vm の前に get_vm_status を使用してください
3. スナップショットを使用する: 大きな変更を行う前にスナップショットを作成してください
4. タスクを監視する: get_node_tasks を使用して、時間のかかる操作を追跡してください
5. 500 エラーに対処する: Proxmox は 404 ではなく 500 を返すことがあります。状況を確認してください
6. 自己署名証明書には SSL モードを使用する: ほとんどの Proxmox インストール環境では自己署名証明書が使われています。verify モードを使用してください

---

ライセンス

MIT ライセンス - @bldg-7/proxmox-mcp パッケージの一部