proxmox/README.md

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)

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.