Proxmox Project Workspace

This workspace contains multiple Proxmox-related projects managed as a monorepo using pnpm workspaces.

Project Structure

• mcp-proxmox/ - Proxmox MCP (Model Context Protocol) Server - Node.js-based server for interacting with Proxmox hypervisors
• ProxmoxVE/ - ProxmoxVE Helper Scripts - Collection of scripts and frontend for managing Proxmox containers and VMs
• smom-dbis-138-proxmox/ - Deployment scripts and configurations for specific use cases

Prerequisites

• Node.js 16+
• pnpm 8+
• Git (for submodule management)

Setup

Quick Setup

Run the automated setup script:

./scripts/setup.sh

This will:

• Create .env file from template (if it doesn't exist)
• Create Claude Desktop configuration (if it doesn't exist)
• Install all workspace dependencies

Manual Setup

1. Clone the repository (if not already done):

   git clone <repository-url>
   cd proxmox
   

2. Initialize and update submodules:

   git submodule update --init --recursive
   

3. Install dependencies:

   pnpm install
   

4. Configure environment:

   # Copy .env template
   cp .env.example ~/.env
   # Edit with your Proxmox credentials
   nano ~/.env
   

5. Configure Claude Desktop:

   # Copy config template
   mkdir -p ~/.config/Claude
   cp claude_desktop_config.json.example ~/.config/Claude/claude_desktop_config.json
   # Verify the path in the config file is correct
   

6. Verify setup:

   ./scripts/verify-setup.sh
   

This will install dependencies for all workspace packages and set up configuration files.

Available Scripts

From the root directory, you can run:

MCP Server Commands

• pnpm mcp:start - Start the Proxmox MCP server
• pnpm mcp:dev - Start the MCP server in development mode (with watch)

Frontend Commands

• pnpm frontend:dev - Start the ProxmoxVE frontend development server
• pnpm frontend:build - Build the ProxmoxVE frontend for production
• pnpm frontend:start - Start the production frontend server

Testing

• pnpm test - Run tests (if available)
• pnpm test:basic - Run basic MCP server tests (read-only operations)
• pnpm test:workflows - Run comprehensive workflow tests (requires elevated permissions)

RPC Node Health, Testing, and Remediation (Chain 138)

This repo includes scripts to test all RPC nodes, audit Proxmox storage restrictions, and enforce safe Besu heap sizing to prevent swap/IO thrash.

Run the full health suite (recommended)

PROXMOX_HOST=192.168.11.10 ./scripts/run-rpc-node-suite.sh

• Writes RPC test reports under reports/ (JSON + Markdown).
• Runs remediation in dry-run mode by default.

Apply remediation (only if you intend to change Proxmox / containers)

PROXMOX_HOST=192.168.11.10 ./scripts/run-rpc-node-suite.sh --apply --restart-besu

Individual tools

# Full RPC matrix test (no Proxmox access required)
python3 ./scripts/test-all-rpc-nodes.py

# Proxmox audits
PROXMOX_HOST=192.168.11.10 ./scripts/audit-proxmox-rpc-storage.sh
PROXMOX_HOST=192.168.11.10 ./scripts/audit-proxmox-rpc-besu-heap.sh

# Idempotent remediation (dry-run by default)
PROXMOX_HOST=192.168.11.10 ./scripts/remediate-proxmox-rpc-stability.sh

Workspace Packages

mcp-proxmox-server

The Proxmox MCP server provides a Model Context Protocol interface for managing Proxmox hypervisors.

Features:

• 55+ MCP tools for Proxmox management
• Configurable permission levels (basic vs elevated)
• Secure token-based authentication
• Support for VMs, containers, storage, snapshots, backups, and more

See mcp-proxmox/README.md for detailed documentation.

Configuration: See docs/MCP_SETUP.md for instructions on configuring the MCP server with Claude Desktop.

proxmox-helper-scripts-website

A Next.js frontend for browsing and managing Proxmox helper scripts.

Features:

• Browse available container and VM scripts
• View script details, requirements, and installation instructions
• JSON editor for script metadata
• Category and version management

See ProxmoxVE/frontend/README.md for more information.

Environment Configuration

MCP Server Configuration

The MCP server loads configuration from /home/intlc/.env (one directory up from the project root). Create this file with:

PROXMOX_HOST=your-proxmox-ip-or-hostname
PROXMOX_USER=root@pam
PROXMOX_TOKEN_NAME=your-token-name
PROXMOX_TOKEN_VALUE=your-token-secret
PROXMOX_ALLOW_ELEVATED=false
PROXMOX_PORT=8006

See docs/MCP_SETUP.md for detailed configuration instructions.

Development

Working with Submodules

To update submodules to their latest versions:

git submodule update --remote

To update a specific submodule:

cd mcp-proxmox
git pull origin main
cd ..
git add mcp-proxmox
git commit -m "Update mcp-proxmox submodule"

Adding New Dependencies

To add a dependency to a specific workspace package:

pnpm --filter mcp-proxmox-server add <package-name>
pnpm --filter proxmox-helper-scripts-website add <package-name>

To add a dev dependency:

pnpm --filter <package-name> add -D <package-name>

Project Structure

proxmox/
├── scripts/          # Project root utility scripts
├── docs/             # Project documentation
├── mcp-proxmox/      # MCP Server submodule
├── ProxmoxVE/        # ProxmoxVE Helper Scripts submodule
└── smom-dbis-138-proxmox/  # Deployment scripts submodule

See PROJECT_STRUCTURE.md for detailed structure documentation.

Project Documentation

Setup & Configuration

• docs/MCP_SETUP.md - MCP Server configuration guide
• docs/PREREQUISITES.md - Prerequisites and requirements
• docs/ENV_STANDARDIZATION.md - Environment variable standardization

Quick References

• docs/QUICK_REFERENCE.md - Quick reference for ProxmoxVE scripts
• docs/README_START_HERE.md - Getting started guide

Deployment

• docs/DEPLOYMENT_VALIDATION_REPORT.md - Deployment validation for ml110-01

Project Documentation

• mcp-proxmox/README.md - MCP Server detailed documentation
• ProxmoxVE/README.md - ProxmoxVE scripts documentation

Deployment Status

✅ Ready for Deployment

Current Status: All validations passing (100%)

• ✅ Prerequisites: 33/33 (100%)
• ✅ Deployment Validation: 41/41 (100%)
• ✅ API Connection: Working (Proxmox 9.1.1)
• ✅ Target Node: ml110 (online)

Quick Deploy:

cd smom-dbis-138-proxmox
sudo ./scripts/deployment/deploy-all.sh

See docs/DEPLOYMENT_READINESS.md for complete deployment guide.

Validation

Run comprehensive validation:

./scripts/complete-validation.sh

Individual checks:

• ./scripts/check-prerequisites.sh - Prerequisites validation
• ./scripts/validate-ml110-deployment.sh - Deployment validation
• ./scripts/test-connection.sh - Connection testing

License

This workspace contains multiple projects with different licenses. Please refer to individual project directories for license information.