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

Neater setup

Browse Source
This commit is contained in:
canvrno
2025-02-19 12:02:03 -07:00
parent 62e674e93f
commit 538a4f93e6
2 changed files with 140 additions and 148 deletions
Download Patch File Download Diff File Expand all files Collapse all files

280
README.md
View File

@@ -22,16 +22,17 @@ A Python-based Model Context Protocol (MCP) server for interacting with Proxmox
- ✅ Type-safe implementation with Pydantic - ✅ Type-safe implementation with Pydantic
- 🎨 Rich output formatting with customizable themes - 🎨 Rich output formatting with customizable themes
https://github.com/user-attachments/assets/991c81ff-d260-4e75-86d3-cedb679a3acf
## 📦 Installation ## 📦 Installation
1. Create a directory for your [Cline](https://github.com/cline/cline) MCP servers (if you haven't already): ### Prerequisites
- Python 3.10 or higher
- Git
- A Proxmox server with API access
### Cline Installation
1. Create a directory for your MCP servers:
```bash ```bash
mkdir -p ~/Documents/Cline/MCP mkdir -p ~/Documents/Cline/MCP
cd ~/Documents/Cline/MCP cd ~/Documents/Cline/MCP
@@ -41,20 +42,22 @@ https://github.com/user-attachments/assets/991c81ff-d260-4e75-86d3-cedb679a3acf
```bash ```bash
# Clone the repository # Clone the repository
git clone https://github.com/canvrno/ProxmoxMCP.git git clone https://github.com/canvrno/ProxmoxMCP.git
# Install in development mode with dependencies
pip install -e "proxmox-mcp[dev]"
```
3. Create and verify your configuration:
```bash
# Create config directory in the project root
cd ProxmoxMCP cd ProxmoxMCP
mkdir proxmox-config
cd proxmox-config # 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]"
``` ```
Create `config.json`: 3. Create and configure Proxmox settings:
```bash
# Create config directory
mkdir -p proxmox-config
```
Create `proxmox-config/config.json`:
```json ```json
{ {
"proxmox": { "proxmox": {
@@ -76,58 +79,92 @@ https://github.com/user-attachments/assets/991c81ff-d260-4e75-86d3-cedb679a3acf
} }
``` ```
Important: Verify your configuration: 4. Add to Cline MCP settings:
- Ensure the config file exists at the specified path Edit `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`:
- The `host` field must be properly set to your Proxmox server's hostname or IP address ```json
- You can validate your config by running: {
```bash "mcpServers": {
python3 -c "import json; print(json.load(open('config.json'))['proxmox']['host'])" "github.com/canvrno/ProxmoxMCP": {
``` "command": "/absolute/path/to/ProxmoxMCP/.venv/bin/python",
- This should print your Proxmox host address. If it prints an empty string or raises an error, your config needs to be fixed. "args": [
"-m",
4. The server provides these tools: "proxmox_mcp.server"
- `get_nodes`: List all nodes in the cluster ],
- `get_node_status`: Get detailed status of a node "cwd": "/absolute/path/to/ProxmoxMCP",
- `get_vms`: List all VMs "env": {
- `get_storage`: List available storage "PROXMOX_MCP_CONFIG": "/absolute/path/to/ProxmoxMCP/proxmox-config/config.json"
- `get_cluster_status`: Get cluster status },
- `execute_vm_command`: Run commands in VM consoles "disabled": false,
"autoApprove": []
Requirements: }
- Python 3.9 or higher }
}
## 🛠️ Development Setup
1. Install UV:
```bash
pip install uv
``` ```
2. Clone the repository: Important: Replace `/absolute/path/to/ProxmoxMCP` with your actual installation path.
```bash
git clone https://github.com/canvrno/ProxmoxMCP.git
cd proxmox-mcp
```
3. Create and activate virtual environment: ### For Manual Installation
```bash
# Create venv
uv venv
# Activate venv (Windows) 1. Create and activate a virtual environment:
.venv\Scripts\activate ```bash
# OR Activate venv (Unix/MacOS) # Linux/macOS
python3 -m venv .venv
source .venv/bin/activate source .venv/bin/activate
# Windows (PowerShell)
python -m venv .venv
.\.venv\Scripts\Activate.ps1
``` ```
4. Install dependencies: 2. Install dependencies:
```bash ```bash
# Install with development dependencies # Install build tools
uv pip install -e ".[dev]" pip install --upgrade pip build wheel setuptools
# OR install only runtime dependencies
uv pip install -e . # Install MCP SDK first (required)
pip install git+https://github.com/modelcontextprotocol/python-sdk.git
# Install package with dev dependencies
pip install -e ".[dev]"
``` ```
3. Create configuration:
```bash
# Create config directory
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
```
### Verifying Installation
1. Check Python environment:
```bash
python -c "import proxmox_mcp; print('Installation OK')"
```
2. Run the tests:
```bash
pytest
```
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:
- A successful connection to your Proxmox server
- Or a connection error (if Proxmox details are incorrect)
## ⚙️ Configuration ## ⚙️ Configuration
### Proxmox API Token Setup ### Proxmox API Token Setup
@@ -139,36 +176,15 @@ Requirements:
- Uncheck "Privilege Separation" if you want full access - Uncheck "Privilege Separation" if you want full access
- Save and copy both the token ID and secret - Save and copy both the token ID and secret
### Server Configuration ### Configuration Methods
Configure the server using either a JSON file or environment variables:
#### Using JSON Configuration #### Using JSON Configuration (Recommended)
1. Copy the example configuration: 1. Copy the example configuration:
```bash ```bash
cp config/config.example.json config/config.json cp config/config.example.json proxmox-config/config.json
``` ```
2. Edit `config/config.json`: 2. Edit `proxmox-config/config.json` with your settings (see format above)
```json
{
"proxmox": {
"host": "your-proxmox-host",
"port": 8006,
"verify_ssl": true,
"service": "PVE"
},
"auth": {
"user": "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 #### Using Environment Variables
Set the following environment variables: Set the following environment variables:
@@ -188,7 +204,36 @@ LOG_FORMAT=%(asctime)s... # Default: standard format
LOG_FILE=proxmox_mcp.log # Default: None (stdout) LOG_FILE=proxmox_mcp.log # Default: None (stdout)
``` ```
## 🔧 Available Tools ## 🚀 Running the Server
### Development Mode
For testing and development:
```bash
# Activate virtual environment first
source .venv/bin/activate # Linux/macOS
# OR
.\.venv\Scripts\Activate.ps1 # Windows
# Run the server
python -m proxmox_mcp.server
```
### Claude Desktop Integration
To install the server in Claude Desktop:
```bash
# Basic installation
mcp install proxmox_mcp/server.py
# 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
```
# 🔧 Available Tools
The server provides the following MCP tools for interacting with Proxmox: The server provides the following MCP tools for interacting with Proxmox:
@@ -396,63 +441,10 @@ Execute a command in a VM's console using QEMU Guest Agent.
- Returns error if command execution fails - Returns error if command execution fails
- Includes command output even if command returns non-zero exit code - Includes command output even if command returns non-zero exit code
## 🚀 Running the Server
### Development Mode
For testing and development, use the MCP development server:
```bash
mcp dev proxmox_mcp/server.py
```
### Claude Desktop Integration
To install the server in Claude Desktop:
```bash
# Basic installation
mcp install proxmox_mcp/server.py
# 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
```
### Direct Execution
Run the server directly:
```bash
python -m proxmox_mcp.server
```
## ⚠️ Error Handling
The server implements comprehensive error handling:
- Authentication Errors: When token authentication fails
- Connection Errors: When unable to connect to Proxmox
- Validation Errors: When tool parameters are invalid
- API Errors: When Proxmox API calls fail
All errors are properly logged and returned with descriptive messages.
## 📝 Logging
Logging can be configured through the config file or environment variables:
- Log Levels: DEBUG, INFO, WARNING, ERROR, CRITICAL
- Output: File or stdout
- Format: Customizable format string
Example log output:
```
2025-02-18 19:15:23,456 - proxmox-mcp - INFO - Server started
2025-02-18 19:15:24,789 - proxmox-mcp - INFO - Connected to Proxmox host
2025-02-18 19:15:25,123 - proxmox-mcp - DEBUG - Tool called: get_nodes
```
## 👨‍💻 Development ## 👨‍💻 Development
After activating your virtual environment:
- Run tests: `pytest` - Run tests: `pytest`
- Format code: `black .` - Format code: `black .`
- Type checking: `mypy .` - Type checking: `mypy .`
@@ -474,9 +466,9 @@ proxmox-mcp/
├── tests/ # Test suite ├── tests/ # Test suite
├── config/ ├── config/
│ └── config.example.json # Configuration template │ └── config.example.json # Configuration template
├── setup.sh # Unix setup script
├── setup.ps1 # Windows setup script
├── pyproject.toml # Project metadata and dependencies ├── pyproject.toml # Project metadata and dependencies
├── requirements.in # Core dependencies
├── requirements-dev.in # Development dependencies
└── LICENSE # MIT License └── LICENSE # MIT License
``` ```

8
pyproject.toml
View File

@@ -1,6 +1,6 @@
[build-system] [build-system]
requires = ["hatchling"] requires = ["setuptools>=61.0.0", "wheel"]
build-backend = "hatchling.build" build-backend = "setuptools.build_meta"
[project] [project]
name = "proxmox-mcp" name = "proxmox-mcp"
@@ -11,7 +11,7 @@ authors = [
{name = "Kevin", email = "kevin@example.com"} {name = "Kevin", email = "kevin@example.com"}
] ]
readme = "README.md" readme = "README.md"
license = "MIT" license = {text = "MIT"}
keywords = ["proxmox", "mcp", "virtualization", "cline", "qemu", "lxc"] keywords = ["proxmox", "mcp", "virtualization", "cline", "qemu", "lxc"]
classifiers = [ classifiers = [
"Development Status :: 3 - Alpha", "Development Status :: 3 - Alpha",
@@ -27,7 +27,7 @@ classifiers = [
] ]
dependencies = [ dependencies = [
"mcp>=0.12.0,<2.0.0", "mcp @ git+https://github.com/modelcontextprotocol/python-sdk.git",
"proxmoxer>=2.0.1,<3.0.0", "proxmoxer>=2.0.1,<3.0.0",
"requests>=2.31.0,<3.0.0", "requests>=2.31.0,<3.0.0",
"pydantic>=2.0.0,<3.0.0", "pydantic>=2.0.0,<3.0.0",