Cursor Proxmox MCP

cursor-proxmox-mcp

Cursor ↔ Proxmox VE の正式な MCP 連携 — QEMU VM（ゲストエージェントのネットワーク／ファイル／ゲスト情報／fsfreeze、および bootstrap_cloudinit_vm ／ provision_vm ／ qm_set_vm を含む）、LXC（provision_lxc、bootstrap_docker_lxc、crun Path B、DNS／SSH ヘルパー、deploy_node_app を含む）、ゲストの電源操作の統合、ストレージ管理（PBS プラグインおよびステータスを含む）、クラスター／タスク（参加を含む）、スナップショット、バックアップ、移行、HA、ファイアウォール、アクセス制御、レプリケーション、SDN の書き込みと適用、ACME の発行／更新、Ceph のステータス／プールと条件付き OSD 作成／破棄、ノードネットワークの CRUD、コンソールチケット／get_console_connection、ホストの再起動／シャットダウンを網羅する 212 個のツールです。v1.9.0 では、オプションの二重認証情報による昇格モード（auth_write、D31）、provision_vm、および Cursor の day-2 自動承認ドキュメントが追加されました。

リポジトリ： hackmods/cursor-proxmox-mcp

ドキュメント： セットアップガイド · Wiki (docs/wiki/) · 公開 · セキュリティ · コントリビューション · API 対応状況 · 変更履歴

MCP ツール

tools/register.py を介して登録されます（ProxmoxMCPServer._setup_tools() から呼び出されます）。ツール一覧は tools/inventory.py / tests/expected_tools.py で固定されており、差異があると CI が失敗します。

ドメイン	ツール
ノード	get_nodes、get_node_status、list_node_networks ＋ 作成／更新／削除 ＋ reload_node_network、get_node_subscription、list_node_certificates、get_node_report、list_node_services、get_node_time、wake_node、reboot_node / shutdown_node（confirm=<node>）
クラスター / タスク	get_cluster_status、get_next_vmid、get_task_status、list_tasks、wait_for_task、get_version、get_mcp_capabilities、get_cluster_resources、get_cluster_log、get_cluster_options、get_cluster_join_info、join_cluster（confirm=JOIN）
QEMU	ライフサイクル ＋ 設定（ISO/cloud-init/net/onboot/tags/description。wait=true は任意）＋ get_vm_network / get_vm_guest_info / fsfreeze_vm / fsthaw_vm / push_to_vm / pull_from_vm（ゲストエージェント）＋ bootstrap_cloudinit_vm / provision_vm（一括で作成、またはクローン→CI→IP）＋ qm_set_vm ＋ get_vm_status、get_vm_rrd_data、コンソールチケット
LXC	ライフサイクル ＋ 設定 ＋ 一時停止／再開（CRIU の警告あり）＋ get_lxc_status / get_lxc_network / get_lxc_rrd_data ＋ VNC/SPICE/termproxy。作成時の ssh_public_keys / docker_ready / nameserver / wait / onboot / description / tags。provision_lxc（一括で作成→起動→IP→SSH）/ bootstrap_docker_lxc / prepare_lxc_for_docker（`docker_mode=auto
ゲスト（統合）	start/stop/shutdown/reboot/delete_guest、get_guest_status、get_guest_pending、move_guest_disk、get_console_connection（guest_type）
スナップショット / バックアップ	スナップショットの CRUD／ロールバック。一括バックアップの CRUD。スケジュール設定された list/create/delete_backup_job
ストレージ	一覧、コンテンツ、list_os_templates、list_isos、ダウンロード URL、定義の CRUD。PBS は create_storage(type=pbs) ＋ get_pbs_storage_status で利用
マイグレーション / HA	migrate_guest。HA グループ ＋ リソースの CRUD
ファイアウォール	クラスター ＋ ゲストのルール／オプション。エイリアス。IP セット ＋ CIDR メンバー。マクロ
アクセス	ユーザー、グループ、ロール、ACL、トークン、get_permissions、get_token_permissions
レプリケーション	ジョブの一覧／状態確認／実行／作成／更新／削除
SDN	ゾーン／VNet／サブネットの CRUD ＋ コントローラー／IPAM／DNS の一覧 ＋ apply_sdn
ACME	一覧 ＋ アカウント／プラグインの作成、プラグインの削除、order_acme_certificate / renew_acme_certificate
Ceph	状態、プール／OSD／MON／MGR の一覧、プールの CRUD。OSD 操作は段階的に実行します：list_node_disks → propose_ceph_osd → create_ceph_osd/destroy_ceph_osd（型指定された確認が必要。作成時のデフォルトは dry_run=true）
プール	一覧／取得／作成／更新／削除

推奨するエージェントのフロー

1. get_next_vmid → list_os_templates / list_isos → list_node_networks
2. provision_lxc / provision_vm（推奨の一括処理）、または create_lxc / create_vm → wait_for_task → 起動
3. リスクのある変更の前に create_snapshot → update_*_config → get_guest_pending → 必要に応じて再起動
4. 必要に応じて migrate_guest / HA / ファイアウォール / アクセス / レプリケーション

ゲストの種類が不明ですか？ guest_type=qemu|lxc を指定して、統合ツール（start_guest、stop_guest、shutdown_guest、reboot_guest、delete_guest、get_guest_status）を優先してください。既存のプロンプトとの互換性のため、並行して *_vm / *_lxc という名前も引き続き利用できます。

インストール

前提条件

• uv（推奨）または Python 3.10+
• Proxmox API トークン

パス 1 — uvx（推奨）

PyPI のパッケージ名は cursor-proxmox-mcp です（コンソールスクリプト：cursor-proxmox-mcp、エイリアス：proxmox-mcp-server／proxmox-mcp）。

注： 無関係な PyPI プロジェクト proxmox-mcp-server は別のコードベースです。必ず cursor-proxmox-mcp をインストールしてください。

# Install uv if needed:  pip install uv   OR   winget install astral-sh.uv

# After PyPI publish (GitHub Release → publish.yml):
uvx cursor-proxmox-mcp

# From a local checkout (dev / before first publish):
uvx --from . cursor-proxmox-mcp

Cursor MCP（公開済みパッケージ — チェックアウト不要）：

{
  "mcpServers": {
    "proxmox": {
      "command": "uvx",
      "args": ["cursor-proxmox-mcp"],
      "env": {
        "PROXMOX_MCP_CONFIG": "C:/Users/YOU/proxmox-config/config.json"
      }
    }
  }
}

ローカルのチェックアウトを使用する場合は、代わりに "args": ["--from", "C:/Users/YOU/Projects/cursor-proxmox-mcp", "cursor-proxmox-mcp"] を使用してください。

uvx を使う理由：依存関係を分離された一時的な環境に解決するため、Cursor が手動管理の venv／PYTHONPATH に依存しません。

パス 2 — ソースから uv を使用

git clone https://github.com/hackmods/cursor-proxmox-mcp.git
cd cursor-proxmox-mcp
uv venv
# Windows: .\.venv\Scripts\Activate.ps1
# Linux/macOS: source .venv/bin/activate
uv pip install -e ".[dev]"
cp proxmox-config/config.example.json proxmox-config/config.json
# Edit host + token, then:
uv run cursor-proxmox-mcp

パス 3 — pip による代替手段

python -m venv .venv
# activate venv
pip install -e ".[dev]"
# optional OpenAPI bridge: pip install -e ".[openapi]"
$env:PROXMOX_MCP_CONFIG="proxmox-config\config.json"   # PowerShell
python -m proxmox_mcp.server

Cursor MCP（Python を直接使用 — 絶対パスを指定してください）：

{
  "mcpServers": {
    "proxmox": {
      "command": "python",
      "args": ["-m", "proxmox_mcp.server"],
      "cwd": "C:/Users/YOU/Projects/cursor-proxmox-mcp",
      "env": {
        "PROXMOX_MCP_CONFIG": "C:/Users/YOU/Projects/cursor-proxmox-mcp/proxmox-config/config.json",
        "PYTHONPATH": "C:/Users/YOU/Projects/cursor-proxmox-mcp/src"
      }
    }
  }
}

新しいツールを取得した後は、Cursor で proxmox MCP サーバーを再起動してください。手動起動スクリプト：start.bat（Windows）／start.sh（Unix） — mcp.json では uvx cursor-proxmox-mcp の使用を推奨します。

検証／ローカル CI

.\scripts\ci-local.ps1

./scripts/ci-local.sh

実行内容：編集可能なインストール → エントリーポイントのスモークテスト → ruff → pytest → インベントリの最低件数チェック（≥100 ツール）。

トラブルシューティング

症状	対処方法
spawn uvx ENOENT	uv をインストールします（pip install uv または winget install astral-sh.uv）。その後、Cursor を再起動してください
ModuleNotFoundError: proxmox_mcp	uvx／uv run を使用するか、通常の python では PYTHONPATH=.../src を設定してください
ModuleNotFoundError: mcp.server.fastmcp	MCP SDK v2 では FastMCP が削除されています。このサーバーは mcp<2 に固定されています。このチェックアウトから再インストールしてください（pip install -e ".[dev]"／uvx --from .）。これにより上限が適用されます
PROXMOX_MCP_CONFIG ... must be set	環境変数を proxmox-config/config.json（絶対パス）に設定してください
認証は成功するがデータが空／不審な 403	トークン ACL を設定せずに権限分離を Yes にしている可能性があります。SETUP.md を参照してください
HA／ファイアウォール／keyctl で 403	トークンには昇格したロールが必要です。可能な場合は root@pam より、スコープを限定した mcp@pve を優先してください
Cursor にツールが表示されない	git pull 後に MCP サーバーを再起動してください

初回のクラスタ設定（トークン、privsep、Cursor の JSON、プロンプトの例）：SETUP.md。LXC シェル／ランタイム IP には、ホスト SSH のオプトイン設定（authorized_keys、任意の host_overrides、MCP の再読み込み）が必要です：SETUP.md — LXC exec 用 SSH。

設定

proxmox-config/config.json の例：

{
  "proxmox": {
    "host": "PROXMOX_HOST",
    "port": 8006,
    "verify_ssl": false,
    "service": "PVE"
  },
  "auth": {
    "user": "USER@pve",
    "token_name": "TOKEN_NAME",
    "token_value": "TOKEN_VALUE"
  },
  "logging": {
    "level": "INFO",
    "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
    "file": "proxmox_mcp.log",
    "verbose": false,
    "tool_calls": true
  }
}

ツール呼び出しは tool_call name=… ok=… duration_ms=… としてログファイルに記録されます（シークレットは伏せられます）。urllib3 の大量出力を抑えたまま詳細な診断を有効にするには、verbose: true を設定するか、環境変数 PROXMOX_MCP_VERBOSE=1 を設定してください。詳細： proxmox-config/README.md — ロギング。

Proxmox UI でトークンを作成します：Datacenter → Permissions → API Tokens。手順の詳細は SETUP.md — API トークンと権限分離 を参照してください。

権限分離： Yes（デフォルト）のままにし、ACL をトークン（user@realm!tokenid）に付与してください。No にすると、トークンはユーザーのすべての権限を継承します（ラボ環境でよく使われる手軽な方法ですが、漏えい時の影響範囲が大きくなります）。使用するツールに対応するロールを付与してください（HA／ファイアウォール／アクセス制御には PVEAuditor、PVEVMAdmin、Datastore.*、Sys.Audit／Sys.Modify）。

シークレットが JSON ファイルに含まれないよう、設定では "token_value": "${PROXMOX_TOKEN_VALUE}" を使用し、Cursor MCP の設定で環境変数を設定してください。

セキュリティ

このサーバーでは、ゲストの作成／削除、ファイアウォール／ACL の変更、ゲストコマンドの実行が可能です。API トークンは本番環境のインフラ認証情報と同様に扱ってください。ポリシーの全文は SECURITY.md を参照してください。

機能

• proxmoxer によるトークン認証（JSON 設定＋オプションの ${ENV} シークレット補間）
• 構造化された tool_call 監査ログ（機密情報をマスキング）＋verbose／環境変数によるログ設定の上書き
• ゲストのライフサイクル全般、スナップショット、vzdump バックアップ
• ストレージコンテンツ＋定義の CRUD＋URL ダウンロード
• クラスター HA、ファイアウォール（ルール／エイリアス／IP セット）、アクセス／ACL／トークン
• レプリケーションジョブ、SDN の書き込み＋適用、ACME の注文／更新、Ceph のステータス／プール、プール
• コンソール チケットの発行＋get_console_connection（VNC／SPICE／termproxy）— WebSocket プロキシなし（D6）
• PVE ストレージプラグインとしての PBS（PBS 製品全体の管理ではありません）；ノードネットワークの CRUD＋再読み込み
• uvx／uv／pip／Docker（GHCR）のインストール方法；mcpo 用のオプション .[openapi]
• ローカル＋GitHub CI（ruff＋pytest＋カバレッジ＋インベントリ＋設計上の不変条件）

対応対象外として確定した項目（不足ではありません — D30）

以下は今後対応予定の不足項目として扱わないでください。長時間接続する VNC／SPICE WebSocket プロキシ（チケット発行のみ — D6）、PBS 製品全体の管理、または制限なしの Ceph OSD／MON／MGR の作成／破棄。制限付きの OSD ツールは提供済みです。MON／MGR のライフサイクル管理には Ceph／PVE のツールを使用してください。

開発

.\scripts\ci-local.ps1

ツールを追加した後は、definitions.py、README の表、.cursor/research/proxmox-api-coverage.md、.cursor/research/next-expansion.md（計画済みの項目を完了した場合）、および tests/expected_tools.py を更新してください。

ステータス

• 複数ドメインにわたる Proxmox API の正式なカバレッジ（212 ツール）
• Phase B＋Phase D のエージェント QOL ツール
• Phase F LXC の運用開始後の管理＋Phase F.1 VM ネットワーク／プッシュ＋作成時の待機オプトイン
• Phase C 軽量版：ノードの再起動／シャットダウン＋クラスターへの参加（型付き確認）
• Phase C 残り：SDN 書き込み／ACME／Ceph プール／コンソールヘルパー／PBS ストレージ／ノードネットワーク CRUD
• Ceph OSD の制限付き作成／破棄（確認＋ドライランをデフォルトに設定）
• v1.0 のセキュリティ強化、コード設計監査、全テストスイート
• uvx cursor-proxmox-mcp＋PyPI／GHCR リリースワークフロー
• カバレッジ＋設計上の不変条件を含むローカル＋GitHub CI

ライセンス

MIT

謝辞

ProxmoxMCP／canvrno/ProxmoxMCP を基にしています。Cursor IDE 向けに、正式な Proxmox VE 統合として拡張しました。