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

Clone the repository (if not already done):
```
git clone <repository-url>
cd proxmox
```

Initialize and update submodules:

git submodule update --init --recursive

Install dependencies:
```
pnpm install
```

Configure environment:

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

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

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.