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/ - Blockchain network and services (Chain 138); smom-dbis-138-proxmox/ - Deployment scripts (if present)
For the full submodule list and relationships, see docs/11-references/SUBMODULE_RELATIONSHIP_MAP.md
Documentation: docs/README.md · docs/MASTER_INDEX.md · Next steps: docs/00-meta/NEXT_STEPS_INDEX.md. Root status reports moved to docs/archive/ (2026-02-20).

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). Canonical source is Gitea (use Gitea for clone and internal repo references; public references such as GRU Monetary Policy and token lists remain on GitHub where applicable):
```
git clone https://gitea.d-bis.org/d-bis/proxmox.git
cd proxmox
```

Initialize and update submodules:

git submodule update --init --recursive

Install dependencies:
```
pnpm install
```

Configure environment:

# Recommended: run setup to create .env in repo root and ~/.env from .env.example
./scripts/setup.sh
# Or manually: copy template to repo root and/or home
cp .env.example .env
# and/or: cp .env.example ~/.env
# Edit with your Proxmox, Cloudflare, NPM credentials (see .env.example)
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)

UniFi Commands

pnpm unifi:build - Build UniFi API and MCP server packages
pnpm unifi:start - Start the UniFi MCP server
pnpm unifi:dev - Start the UniFi MCP server in development mode
pnpm unifi:cli - Run UniFi CLI tool

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.

unifi-api & mcp-unifi-server

UniFi API client library and MCP server for managing Ubiquiti UniFi/UDM Pro devices.

Features:

Type-safe API client with full TypeScript support
Dual API mode support (Official Local API and Private Controller API)
MCP server for Claude Desktop integration
CLI tool for common operations
Utility scripts for monitoring and health checks

See unifi-api/README.md for API client documentation. See mcp-unifi/README.md for MCP server documentation.

Configuration: See docs/04-configuration/UNIFI_API_SETUP.md for setup instructions.

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
├── fireblocks-integration/  # Fireblocks Web3 (Chain 138) submodule (Gitea)
└── smom-dbis-138-proxmox/  # Deployment scripts submodule

See PROJECT_STRUCTURE.md for detailed structure documentation.

How to Navigate This Repo

New to this repository? Start here:

ROOT_INDEX.md - Quick navigation index for newcomers and auditors
DIRECTORY_REFERENCE.md - Complete directory structure and organization guide
docs/MASTER_INDEX.md - Documentation index (deployment, architecture, services)
PROJECT_STRUCTURE.md - Project and docs structure

Organization principles: This repository uses a flat + indexed structure. The three-layer separation (control plane / core systems / ops evidence) is a mental model, not an enforced structure. See docs/MASTER_INDEX.md and PROJECT_STRUCTURE.md for structure and intent.

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/12-quick-reference/QUICK_REFERENCE.md - Quick reference for ProxmoxVE scripts
docs/12-quick-reference/QUICK_REFERENCE_CARDS.md - Network, VMID, commands, troubleshooting cards
docs/01-getting-started/README_START_HERE.md - Getting started guide

Deployment

docs/03-deployment/DEPLOYMENT_STATUS_CONSOLIDATED.md - Deployment status
docs/03-deployment/DEPLOYMENT_READINESS.md - Deployment readiness checklist
Next steps (master list): docs/00-meta/NEXT_STEPS_MASTER.md
CCIP WETH9 Bridge (Chain 138): ./scripts/deploy-and-configure-weth9-bridge-chain138.sh (use --dry-run to simulate) then set CCIPWETH9_BRIDGE_CHAIN138; see COMPREHENSIVE_STATUS_BRIDGE_READY.md, docs/07-ccip/README.md, scripts/README.md

Project Documentation

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

Multi-Chain Integration

ALL Mainnet Integration - Complete ALL Mainnet (651940) integration guide
ALL Mainnet Master Documentation - Quick reference for ALL Mainnet configuration

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/03-deployment/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.