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

Cline Install Notes v2

Browse Source
This commit is contained in:
canvrno
2025-02-19 12:33:13 -07:00
parent ed6f30be5b
commit 2d45c0edcd
3 changed files with 97 additions and 240 deletions
Download Patch File Download Diff File Expand all files Collapse all files

145
ClineInstall.md
View File

@@ -1,145 +0,0 @@
# 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"}
)

192
README.md
View File

@@ -25,58 +25,68 @@ A Python-based Model Context Protocol (MCP) server for interacting with Proxmox
## 📦 Installation
### Prerequisites
- UV package manager (recommended)
- Python 3.10 or higher
- Git
- A Proxmox server with API access
- Access to a Proxmox server with API token credentials
### For Cline
Before starting, ensure you have:
- [ ] Proxmox server hostname or IP
- [ ] Proxmox API token (see [API Token Setup](#proxmox-api-token-setup))
- [ ] UV installed (`pip install uv`)
**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
### Option 1: Quick Install (Recommended)
The ClineInstall.md guide is optimized for programmatic installation and includes all necessary environment variables and configuration details.
### For Manual Installation
1. Create and activate a virtual environment:
1. Clone and set up environment:
```bash
# Linux/macOS
python3 -m venv .venv
source .venv/bin/activate
# Clone repository
cd ~/Documents/Cline/MCP # For Cline users
# OR
cd your/preferred/directory # For manual installation
# Windows (PowerShell)
python -m venv .venv
.\.venv\Scripts\Activate.ps1
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:
```bash
# Install build tools
pip install --upgrade pip build wheel setuptools
# Install MCP SDK first (required)
pip install git+https://github.com/modelcontextprotocol/python-sdk.git
# Install package with dev dependencies
pip install -e ".[dev]"
# Install with development dependencies
uv pip install -e ".[dev]"
```
3. Create configuration:
```bash
# Create config directory
# Create config directory and copy template
mkdir -p proxmox-config
# Copy example config
cp config/config.example.json proxmox-config/config.json
```
# Edit the config with your Proxmox details
# See Configuration section below
4. Edit `proxmox-config/config.json`:
```json
{
"proxmox": {
"host": "PROXMOX_HOST", # Required: Your Proxmox server address
"port": 8006, # Optional: Default is 8006
"verify_ssl": false, # Optional: Set false for self-signed certs
"service": "PVE" # Optional: Default is PVE
},
"auth": {
"user": "USER@pve", # Required: Your Proxmox username
"token_name": "TOKEN_NAME", # Required: API token name
"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
@@ -115,53 +125,6 @@ The ClineInstall.md guide is optimized for programmatic installation and include
- Uncheck "Privilege Separation" if you want full access
- Save and copy both the token ID and secret
### Configuration Methods
#### Using JSON Configuration (Recommended)
1. Copy the example configuration:
```bash
cp config/config.example.json proxmox-config/config.json
```
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:
```bash
# Required
PROXMOX_HOST=your-host
PROXMOX_USER=username@pve
PROXMOX_TOKEN_NAME=your-token-name
PROXMOX_TOKEN_VALUE=your-token-value
# Optional
PROXMOX_PORT=8006 # Default: 8006
PROXMOX_VERIFY_SSL=true # Default: true
PROXMOX_SERVICE=PVE # Default: PVE
LOG_LEVEL=INFO # Default: INFO
LOG_FORMAT=%(asctime)s... # Default: standard format
LOG_FILE=proxmox_mcp.log # Default: None (stdout)
```
## 🚀 Running the Server
@@ -177,21 +140,61 @@ source .venv/bin/activate # Linux/macOS
python -m proxmox_mcp.server
```
### Claude Desktop Integration
To install the server in Claude Desktop:
```bash
# Basic installation
mcp install proxmox_mcp/server.py
### Cline Desktop Integration
# Installation with custom name and environment variables
mcp install proxmox_mcp/server.py \
--name "Proxmox Manager" \
-v PROXMOX_HOST=your-host \
-v PROXMOX_USER=username@pve \
-v PROXMOX_TOKEN_NAME=your-token \
-v PROXMOX_TOKEN_VALUE=your-secret
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`):
```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": []
}
}
}
```
To help generate the correct paths, you can use this command:
```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
The server provides the following MCP tools for interacting with Proxmox:
@@ -354,9 +357,8 @@ proxmox-mcp/
│ │ └── console/ # VM console operations
│ └── utils/ # Utilities (auth, logging)
├── tests/ # Test suite
├── config/
├── proxmox-config/
│ └── config.example.json # Configuration template
├── ClineInstall.md # Cline-specific installation guide
├── pyproject.toml # Project metadata and dependencies
└── LICENSE # MIT License
```

0
config/config.example.json → proxmox-config/config.example.json
View File