d-bis/mcp-proxmox
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README with credits and Node.js implementation details

Browse Source 
- Credit original Python implementation by canvrno/ProxmoxMCP
- Document architecture changes from Python to Node.js
- Explain new configurable permission system
- Update tool names with proxmox_ prefix
- Simplify installation and configuration instructions
- Remove Python-specific content and dependencies
This commit is contained in:
gilby125
2025-06-05 14:37:10 -05:00
parent d534c5e24e
commit 87eb9cfd0e
1 changed files with 95 additions and 159 deletions
Download Patch File Download Diff File Expand all files Collapse all files

254
README.md
View File

@@ -1,26 +1,44 @@
# 🚀 Proxmox Manager - Proxmox MCP Server # 🚀 Proxmox MCP Server (Node.js Edition)
![ProxmoxMCP](https://github.com/user-attachments/assets/e32ab79f-be8a-420c-ab2d-475612150534) A Node.js-based Model Context Protocol (MCP) server for interacting with Proxmox hypervisors, providing a clean interface for managing nodes, VMs, and containers with configurable permission levels.
A Python-based Model Context Protocol (MCP) server for interacting with Proxmox hypervisors, providing a clean interface for managing nodes, VMs, and containers. ## 🙏 Credits
This project is based on the original Python implementation by [canvrno/ProxmoxMCP](https://github.com/canvrno/ProxmoxMCP). This Node.js version maintains the same core functionality while adapting it for JavaScript/Node.js environments and adding configurable permission management.
## 🔄 Changes from Original
**Architecture Changes:**
- ✅ Complete rewrite from Python to Node.js
- ✅ Uses `@modelcontextprotocol/sdk` instead of Python MCP SDK
- ✅ Environment variable configuration instead of JSON config files
- ✅ Simplified dependency management with npm
**New Features:**
- 🔒 **Configurable Permission Levels**: `PROXMOX_ALLOW_ELEVATED` setting for security
- 🛡️ **Basic Mode**: Safe operations (node listing, VM status) with minimal permissions
- 🔓 **Elevated Mode**: Advanced features (detailed metrics, command execution) requiring full permissions
- 📝 **Better Error Handling**: Clear permission warnings and graceful degradation
- 🔧 **Auto Environment Loading**: Automatically loads `.env` files from parent directories
## 🏗️ Built With ## 🏗️ Built With
- [Cline](https://github.com/cline/cline) - Autonomous coding agent - Go faster with Cline. - [Node.js](https://nodejs.org/) - JavaScript runtime
- [Proxmoxer](https://github.com/proxmoxer/proxmoxer) - Python wrapper for Proxmox API - [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/sdk) - Model Context Protocol SDK for Node.js
- [MCP SDK](https://github.com/modelcontextprotocol/sdk) - Model Context Protocol SDK - [node-fetch](https://github.com/node-fetch/node-fetch) - HTTP client for API requests
- [Pydantic](https://docs.pydantic.dev/) - Data validation using Python type annotations - [Claude Code](https://claude.ai/code) - AI coding assistant integration
## ✨ Features ## ✨ Features
- 🤖 Full integration with Cline - 🔒 **Configurable Security**: Two permission levels for safe operation
- 🛠️ Built with the official MCP SDK - 🛠️ Built with the official MCP SDK for Node.js
- 🔒 Secure token-based authentication with Proxmox - 🔐 Secure token-based authentication with Proxmox
- 🖥️ Tools for managing nodes and VMs - 🖥️ Comprehensive node and VM management
- 💻 VM console command execution - 💻 VM console command execution (elevated mode)
- 📝 Configurable logging system - 📊 Real-time resource monitoring
- ✅ Type-safe implementation with Pydantic - 🎨 Rich markdown-formatted output
- 🎨 Rich output formatting with customizable themes - ⚡ Fast Node.js performance
- 🔧 Easy environment-based configuration
@@ -31,94 +49,65 @@ https://github.com/user-attachments/assets/1b5f42f7-85d5-4918-aca4-d38413b0e82b
## 📦 Installation ## 📦 Installation
### Prerequisites ### Prerequisites
- UV package manager (recommended) - Node.js 16+ and npm
- Python 3.10 or higher
- Git - Git
- Access to a Proxmox server with API token credentials - Access to a Proxmox server with API token credentials
Before starting, ensure you have: Before starting, ensure you have:
- [ ] Node.js and npm installed
- [ ] Proxmox server hostname or IP - [ ] Proxmox server hostname or IP
- [ ] Proxmox API token (see [API Token Setup](#proxmox-api-token-setup)) - [ ] Proxmox API token (see [API Token Setup](#proxmox-api-token-setup))
- [ ] UV installed (`pip install uv`)
### Option 1: Quick Install (Recommended) ### Quick Install
1. Clone and set up environment: 1. Clone and set up:
```bash ```bash
# Clone repository git clone https://github.com/gilby125/mcp-proxmox.git
cd ~/Documents/Cline/MCP # For Cline users cd mcp-proxmox
# OR npm install
cd your/preferred/directory # For manual installation
git clone https://github.com/canvrno/ProxmoxMCP.git
cd ProxmoxMCP
# Create and activate virtual environment
uv venv
source .venv/bin/activate # Linux/macOS
# OR
.\.venv\Scripts\Activate.ps1 # Windows
``` ```
2. Install dependencies: 2. Create `.env` file with your Proxmox configuration:
```bash ```bash
# Install with development dependencies # Proxmox Configuration
uv pip install -e ".[dev]" PROXMOX_HOST=192.168.1.100
PROXMOX_USER=root@pam
PROXMOX_TOKEN_NAME=mcp-server
PROXMOX_TOKEN_VALUE=your-token-value-here
PROXMOX_PORT=8006
PROXMOX_ALLOW_ELEVATED=false # Set to 'true' for advanced features
``` ```
3. Create configuration: ### Permission Levels
```bash
# Create config directory and copy template
mkdir -p proxmox-config
cp config/config.example.json proxmox-config/config.json
```
4. Edit `proxmox-config/config.json`: **Basic Mode** (`PROXMOX_ALLOW_ELEVATED=false`):
```json - List cluster nodes and their status
{ - List VMs and containers
"proxmox": { - Basic cluster health overview
"host": "PROXMOX_HOST", # Required: Your Proxmox server address - Requires minimal API token permissions
"port": 8006, # Optional: Default is 8006
"verify_ssl": false, # Optional: Set false for self-signed certs **Elevated Mode** (`PROXMOX_ALLOW_ELEVATED=true`):
"service": "PVE" # Optional: Default is PVE - All basic features plus:
}, - Detailed node resource metrics
"auth": { - VM command execution
"user": "USER@pve", # Required: Your Proxmox username - Advanced cluster statistics
"token_name": "TOKEN_NAME", # Required: API token ID - Requires API token with `Sys.Audit`, `VM.Monitor`, `VM.Console` permissions
"token_value": "TOKEN_VALUE" # Required: API token value
},
"logging": {
"level": "INFO", # Optional: DEBUG for more detail
"format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
"file": "proxmox_mcp.log" # Optional: Log to file
}
}
```
### Verifying Installation ### Verifying Installation
1. Check Python environment: 1. Test the MCP server:
```bash ```bash
python -c "import proxmox_mcp; print('Installation OK')" echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node index.js
``` ```
2. Run the tests: 2. Test a basic API call:
```bash ```bash
pytest echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "proxmox_get_nodes", "arguments": {}}}' | node index.js
```
3. Verify configuration:
```bash
# Linux/macOS
PROXMOX_MCP_CONFIG="proxmox-config/config.json" python -m proxmox_mcp.server
# Windows (PowerShell)
$env:PROXMOX_MCP_CONFIG="proxmox-config\config.json"; python -m proxmox_mcp.server
``` ```
You should see either: You should see either:
- A successful connection to your Proxmox server - A successful list of your Proxmox nodes
- Or a connection error (if Proxmox details are incorrect) - Or a connection/permission error with helpful guidance
## ⚙️ Configuration ## ⚙️ Configuration
@@ -134,78 +123,34 @@ Before starting, ensure you have:
## 🚀 Running the Server ## 🚀 Running the Server
### Development Mode ### Direct Execution
For testing and development:
```bash ```bash
# Activate virtual environment first node index.js
source .venv/bin/activate # Linux/macOS
# OR
.\.venv\Scripts\Activate.ps1 # Windows
# Run the server
python -m proxmox_mcp.server
``` ```
### Cline Desktop Integration ### Claude Code Integration
For Cline users, add this configuration to your MCP settings file (typically at `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`): Add this to your Claude Code MCP configuration:
```json ```json
{ {
"mcpServers": { "mcpServers": {
"github.com/canvrno/ProxmoxMCP": { "mcp-proxmox": {
"command": "/absolute/path/to/ProxmoxMCP/.venv/bin/python", "command": "node",
"args": ["-m", "proxmox_mcp.server"], "args": ["index.js"],
"cwd": "/absolute/path/to/ProxmoxMCP", "cwd": "/absolute/path/to/mcp-proxmox"
"env": {
"PYTHONPATH": "/absolute/path/to/ProxmoxMCP/src",
"PROXMOX_MCP_CONFIG": "/absolute/path/to/ProxmoxMCP/proxmox-config/config.json",
"PROXMOX_HOST": "your-proxmox-host",
"PROXMOX_USER": "username@pve",
"PROXMOX_TOKEN_NAME": "token-name",
"PROXMOX_TOKEN_VALUE": "token-value",
"PROXMOX_PORT": "8006",
"PROXMOX_VERIFY_SSL": "false",
"PROXMOX_SERVICE": "PVE",
"LOG_LEVEL": "DEBUG"
},
"disabled": false,
"autoApprove": []
}
} }
}
} }
``` ```
To help generate the correct paths, you can use this command: The server will automatically load environment variables from `.env` files in the current directory or parent directories.
```bash
# This will print the MCP settings with your absolute paths filled in
python -c "import os; print(f'''{{
\"mcpServers\": {{
\"github.com/canvrno/ProxmoxMCP\": {{
\"command\": \"{os.path.abspath('.venv/bin/python')}\",
\"args\": [\"-m\", \"proxmox_mcp.server\"],
\"cwd\": \"{os.getcwd()}\",
\"env\": {{
\"PYTHONPATH\": \"{os.path.abspath('src')}\",
\"PROXMOX_MCP_CONFIG\": \"{os.path.abspath('proxmox-config/config.json')}\",
...
}}
}}
}}
}}''')"
```
Important:
- All paths must be absolute
- The Python interpreter must be from your virtual environment
- The PYTHONPATH must point to the src directory
- Restart VSCode after updating MCP settings
# 🔧 Available Tools # 🔧 Available Tools
The server provides the following MCP tools for interacting with Proxmox: The server provides the following MCP tools for interacting with Proxmox:
### get_nodes ### proxmox_get_nodes
Lists all nodes in the Proxmox cluster. Lists all nodes in the Proxmox cluster.
- Parameters: None - Parameters: None
@@ -226,7 +171,7 @@ Lists all nodes in the Proxmox cluster.
• Memory: 201.3 GB / 512.0 GB (39.3%) • Memory: 201.3 GB / 512.0 GB (39.3%)
``` ```
### get_node_status ### proxmox_get_node_status
Get detailed status of a specific node. Get detailed status of a specific node.
- Parameters: - Parameters:
@@ -243,7 +188,7 @@ Get detailed status of a specific node.
• Temperature: 38°C • Temperature: 38°C
``` ```
### get_vms ### proxmox_get_vms
List all VMs across the cluster. List all VMs across the cluster.
- Parameters: None - Parameters: None
@@ -264,7 +209,7 @@ List all VMs across the cluster.
• Memory: 12.8 GB / 32.0 GB (40.0%) • Memory: 12.8 GB / 32.0 GB (40.0%)
``` ```
### get_storage ### proxmox_get_storage
List available storage. List available storage.
- Parameters: None - Parameters: None
@@ -285,7 +230,7 @@ List available storage.
• IOPS: ⬆️ 42.8k ⬇️ 35.6k • IOPS: ⬆️ 42.8k ⬇️ 35.6k
``` ```
### get_cluster_status ### proxmox_get_cluster_status
Get overall cluster status. Get overall cluster status.
- Parameters: None - Parameters: None
@@ -310,7 +255,7 @@ Get overall cluster status.
- Average Memory Usage: 42.8% - Average Memory Usage: 42.8%
``` ```
### execute_vm_command ### proxmox_execute_vm_command
Execute a command in a VM's console using QEMU Guest Agent. Execute a command in a VM's console using QEMU Guest Agent.
- Parameters: - Parameters:
@@ -342,31 +287,22 @@ Execute a command in a VM's console using QEMU Guest Agent.
## 👨‍💻 Development ## 👨‍💻 Development
After activating your virtual environment: Development commands:
- Run tests: `pytest` - Install dependencies: `npm install`
- Format code: `black .` - Run server: `npm start`
- Type checking: `mypy .` - Test server: `echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node index.js`
- Lint: `ruff .`
## 📁 Project Structure ## 📁 Project Structure
``` ```
proxmox-mcp/ mcp-proxmox/
├── src/ ├── index.js # Main MCP server implementation
│ └── proxmox_mcp/ ├── package.json # Node.js dependencies and scripts
│ ├── server.py # Main MCP server implementation ├── package-lock.json # Dependency lock file
│ ├── config/ # Configuration handling ├── .env # Environment configuration (not in git)
│ ├── core/ # Core functionality ├── node_modules/ # Dependencies (not in git)
│ ├── formatting/ # Output formatting and themes └── README.md # This documentation
│ ├── tools/ # Tool implementations
│ │ └── console/ # VM console operations
│ └── utils/ # Utilities (auth, logging)
├── tests/ # Test suite
├── proxmox-config/
│ └── config.example.json # Configuration template
├── pyproject.toml # Project metadata and dependencies
└── LICENSE # MIT License
``` ```
## 📄 License ## 📄 License