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

Cline Install Notes

Browse Source
This commit is contained in:
canvrno
2025-02-19 12:19:32 -07:00
parent 538a4f93e6
commit ed6f30be5b
2 changed files with 176 additions and 142 deletions
Download Patch File Download Diff File Expand all files Collapse all files

145
ClineInstall.md Normal file
View File

@@ -0,0 +1,145 @@
# Cline Installation Guide
This guide provides specific instructions for Cline to install and configure the Proxmox MCP server.
## Prerequisites
- UV package manager
- Python 3.9 or higher
- Access to a Proxmox server with API token credentials
## Installation Steps
### 1. Environment Setup
```bash
# Clone repository into Cline MCP directory
cd ~/Documents/Cline/MCP
git clone https://github.com/canvrno/ProxmoxMCP.git
cd ProxmoxMCP
# Create and activate virtual environment using UV
uv venv
source .venv/bin/activate
# Install package in development mode with dependencies
uv pip install -e ".[dev]"
```
### 2. Configuration Setup
Create the config directory and config.json file:
```bash
mkdir -p proxmox-config
```
Create `proxmox-config/config.json` with the following structure:
```json
{
"proxmox": {
"host": "your-proxmox-host", # Hostname or IP of Proxmox server
"port": 8006, # Default Proxmox API port
"verify_ssl": true, # Set to false if using self-signed certs
"service": "PVE" # Default Proxmox service
},
"auth": {
"user": "username@pve", # Proxmox username with @pve suffix
"token_name": "token-name", # API token name
"token_value": "token-value" # API token value
},
"logging": {
"level": "INFO", # DEBUG for more verbose logging
"format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
"file": "proxmox_mcp.log" # Log file name
}
}
```
### 3. MCP Server Configuration
Add the following configuration to the Cline MCP settings file (typically at `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`):
```json
{
"mcpServers": {
"github.com/canvrno/ProxmoxMCP": {
"command": "/absolute/path/to/ProxmoxMCP/.venv/bin/python",
"args": ["-m", "proxmox_mcp.server"],
"cwd": "/absolute/path/to/ProxmoxMCP",
"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": []
}
}
}
```
## Critical Requirements
1. **Virtual Environment**:
- The virtual environment MUST be used for both installation and running the server
- All Python commands should be run within the activated venv
2. **File Paths**:
- ALL paths in the MCP settings must be absolute paths
- The PYTHONPATH must point to the `src` directory
- The PROXMOX_MCP_CONFIG environment variable must point to your config.json file
3. **Environment Variables**:
- PROXMOX_MCP_CONFIG is required for the server to locate your configuration
- All Proxmox-related environment variables can override config.json settings
4. **VSCode Integration**:
- Restart VSCode after updating MCP settings
- The server will be available through the MCP tools interface
## Troubleshooting
1. **Import Errors**:
- Ensure PYTHONPATH is set correctly
- Verify the package is installed in development mode
- Make sure you're using the Python interpreter from the virtual environment
2. **Configuration Errors**:
- Check that PROXMOX_MCP_CONFIG points to a valid config.json file
- Verify all required fields are present in config.json
- Ensure Proxmox credentials are correct
3. **Connection Issues**:
- Verify Proxmox host is reachable
- Check if SSL verification is appropriate for your setup
- Confirm API token has necessary permissions
## Available Tools
Once installed, the following tools will be available:
1. `get_nodes`: List all nodes in the cluster
2. `get_node_status`: Get detailed status of a specific node
3. `get_vms`: List all VMs across the cluster
4. `get_storage`: List available storage
5. `get_cluster_status`: Get cluster status
6. `execute_vm_command`: Run commands in VM consoles
Example usage:
```python
# Get cluster status
use_mcp_tool(
server_name="github.com/canvrno/ProxmoxMCP",
tool_name="get_cluster_status",
arguments={}
)
# Get status of specific node
use_mcp_tool(
server_name="github.com/canvrno/ProxmoxMCP",
tool_name="get_node_status",
arguments={"node": "pve1"}
)

173
README.md
View File

@@ -30,78 +30,17 @@ A Python-based Model Context Protocol (MCP) server for interacting with Proxmox
- Git
- A Proxmox server with API access
### Cline Installation
### For Cline
1. Create a directory for your MCP servers:
```bash
mkdir -p ~/Documents/Cline/MCP
cd ~/Documents/Cline/MCP
```
**IMPORTANT**: If you are Cline, please refer to [ClineInstall.md](ClineInstall.md) for detailed installation instructions specifically designed for you. This file contains:
- Step-by-step installation process
- Virtual environment setup using UV
- Configuration file setup
- MCP server settings
- Troubleshooting guide
- Tool usage examples
2. Clone and install the package:
```bash
# Clone the repository
git clone https://github.com/canvrno/ProxmoxMCP.git
cd ProxmoxMCP
# Install UV if not already installed
pip install uv
# Create and activate virtual environment, then install dependencies
uv venv && source .venv/bin/activate && uv pip install -e ".[dev]"
```
3. Create and configure Proxmox settings:
```bash
# Create config directory
mkdir -p proxmox-config
```
Create `proxmox-config/config.json`:
```json
{
"proxmox": {
"host": "your-proxmox-host", # Must be a valid hostname or IP
"port": 8006,
"verify_ssl": true,
"service": "PVE"
},
"auth": {
"user": "your-username@pve",
"token_name": "your-token-name",
"token_value": "your-token-value"
},
"logging": {
"level": "INFO",
"format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
"file": "proxmox_mcp.log"
}
}
```
4. Add to Cline MCP settings:
Edit `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`:
```json
{
"mcpServers": {
"github.com/canvrno/ProxmoxMCP": {
"command": "/absolute/path/to/ProxmoxMCP/.venv/bin/python",
"args": [
"-m",
"proxmox_mcp.server"
],
"cwd": "/absolute/path/to/ProxmoxMCP",
"env": {
"PROXMOX_MCP_CONFIG": "/absolute/path/to/ProxmoxMCP/proxmox-config/config.json"
},
"disabled": false,
"autoApprove": []
}
}
}
```
Important: Replace `/absolute/path/to/ProxmoxMCP` with your actual installation path.
The ClineInstall.md guide is optimized for programmatic installation and includes all necessary environment variables and configuration details.
### For Manual Installation
@@ -184,7 +123,27 @@ A Python-based Model Context Protocol (MCP) server for interacting with Proxmox
cp config/config.example.json proxmox-config/config.json
```
2. Edit `proxmox-config/config.json` with your settings (see format above)
2. Edit `proxmox-config/config.json`:
```json
{
"proxmox": {
"host": "your-proxmox-host", # Must be a valid hostname or IP
"port": 8006,
"verify_ssl": true,
"service": "PVE"
},
"auth": {
"user": "your-username@pve",
"token_name": "your-token-name",
"token_value": "your-token-value"
},
"logging": {
"level": "INFO",
"format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
"file": "proxmox_mcp.log"
}
}
```
#### Using Environment Variables
Set the following environment variables:
@@ -256,18 +215,6 @@ Lists all nodes in the Proxmox cluster.
• Uptime: ⏳ 156d 11h
• CPU Cores: 64
• Memory: 201.3 GB / 512.0 GB (39.3%)
🖥️ pve-storage-01
• Status: ONLINE
• Uptime: ⏳ 156d 12h
• CPU Cores: 32
• Memory: 89.2 GB / 256.0 GB (34.8%)
🖥️ pve-storage-02
• Status: ONLINE
• Uptime: ⏳ 156d 12h
• CPU Cores: 32
• Memory: 92.8 GB / 256.0 GB (36.2%)
```
### get_node_status
@@ -301,47 +248,11 @@ List all VMs across the cluster.
• CPU Cores: 16
• Memory: 92.3 GB / 128.0 GB (72.1%)
🗃️ prod-db-replica-01 (ID: 101)
• Status: RUNNING
• Node: pve-compute-02
• CPU Cores: 16
• Memory: 86.5 GB / 128.0 GB (67.6%)
🗃️ prod-web-01 (ID: 102)
• Status: RUNNING
• Node: pve-compute-01
• CPU Cores: 8
• Memory: 12.8 GB / 32.0 GB (40.0%)
🗃️ prod-web-02 (ID: 103)
• Status: RUNNING
• Node: pve-compute-02
• CPU Cores: 8
• Memory: 13.2 GB / 32.0 GB (41.3%)
🗃️ prod-cache-01 (ID: 104)
• Status: RUNNING
• Node: pve-compute-01
• CPU Cores: 4
• Memory: 24.6 GB / 64.0 GB (38.4%)
🗃️ prod-cache-02 (ID: 105)
• Status: RUNNING
• Node: pve-compute-02
• CPU Cores: 4
• Memory: 25.1 GB / 64.0 GB (39.2%)
🗃️ staging-env (ID: 106)
• Status: RUNNING
• Node: pve-compute-02
• CPU Cores: 32
• Memory: 48.2 GB / 128.0 GB (37.7%)
🗃️ dev-env (ID: 107)
• Status: STOPPED
• Node: pve-compute-01
• CPU Cores: 16
• Memory: 0.0 GB / 64.0 GB (0.0%)
```
### get_storage
@@ -358,18 +269,6 @@ List available storage.
• Usage: 12.8 TB / 20.0 TB (64.0%)
• IOPS: ⬆️ 15.2k ⬇️ 12.8k
💾 ceph-backup
• Status: ONLINE
• Type: rbd
• Usage: 28.6 TB / 40.0 TB (71.5%)
• IOPS: ⬆️ 8.4k ⬇️ 6.2k
💾 nvme-cache
• Status: ONLINE
• Type: lvmthin
• Usage: 856.2 GB / 2.0 TB (42.8%)
• IOPS: ⬆️ 125.6k ⬇️ 98.4k
💾 local-zfs
• Status: ONLINE
• Type: zfspool
@@ -421,15 +320,6 @@ Execute a command in a VM's console using QEMU Guest Agent.
● nginx.service - A high performance web server and a reverse proxy server
Loaded: loaded (/lib/systemd/system/nginx.service; enabled; vendor preset: enabled)
Active: active (running) since Tue 2025-02-18 15:23:45 UTC; 2 months 3 days ago
Docs: man:nginx(8)
Main PID: 1234 (nginx)
Tasks: 64
Memory: 256.2M
CPU: 42.6h
CGroup: /system.slice/nginx.service
├─1234 "nginx: master process /usr/sbin/nginx -g daemon on; master_pr..."
├─1235 "nginx: worker process" "" "" "" "" "" "" "" "" "" "" "" "" ""
└─1236 "nginx: worker process" "" "" "" "" "" "" "" "" "" "" "" "" ""
```
- Requirements:
- VM must be running
@@ -466,8 +356,7 @@ proxmox-mcp/
├── tests/ # Test suite
├── config/
│ └── config.example.json # Configuration template
├── setup.sh # Unix setup script
├── setup.ps1 # Windows setup script
├── ClineInstall.md # Cline-specific installation guide
├── pyproject.toml # Project metadata and dependencies
└── LICENSE # MIT License
```