Cline Install Notes v2
This commit is contained in:
canvrno
145
ClineInstall.md
145
ClineInstall.md
@@ -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
192
README.md
@@ -25,58 +25,68 @@ A Python-based Model Context Protocol (MCP) server for interacting with Proxmox
|
|||||||
## 📦 Installation
|
## 📦 Installation
|
||||||
|
|
||||||
### Prerequisites
|
### Prerequisites
|
||||||
|
- UV package manager (recommended)
|
||||||
- Python 3.10 or higher
|
- Python 3.10 or higher
|
||||||
- Git
|
- 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:
|
### Option 1: Quick Install (Recommended)
|
||||||
- Step-by-step installation process
|
|
||||||
- Virtual environment setup using UV
|
|
||||||
- Configuration file setup
|
|
||||||
- MCP server settings
|
|
||||||
- Troubleshooting guide
|
|
||||||
- Tool usage examples
|
|
||||||
|
|
||||||
The ClineInstall.md guide is optimized for programmatic installation and includes all necessary environment variables and configuration details.
|
1. Clone and set up environment:
|
||||||
|
|
||||||
### For Manual Installation
|
|
||||||
|
|
||||||
1. Create and activate a virtual environment:
|
|
||||||
```bash
|
```bash
|
||||||
# Linux/macOS
|
# Clone repository
|
||||||
python3 -m venv .venv
|
cd ~/Documents/Cline/MCP # For Cline users
|
||||||
source .venv/bin/activate
|
# OR
|
||||||
|
cd your/preferred/directory # For manual installation
|
||||||
|
|
||||||
|
git clone https://github.com/canvrno/ProxmoxMCP.git
|
||||||
|
cd ProxmoxMCP
|
||||||
|
|
||||||
# Windows (PowerShell)
|
# Create and activate virtual environment
|
||||||
python -m venv .venv
|
uv venv
|
||||||
.\.venv\Scripts\Activate.ps1
|
source .venv/bin/activate # Linux/macOS
|
||||||
|
# OR
|
||||||
|
.\.venv\Scripts\Activate.ps1 # Windows
|
||||||
```
|
```
|
||||||
|
|
||||||
2. Install dependencies:
|
2. Install dependencies:
|
||||||
```bash
|
```bash
|
||||||
# Install build tools
|
# Install with development dependencies
|
||||||
pip install --upgrade pip build wheel setuptools
|
uv pip install -e ".[dev]"
|
||||||
|
|
||||||
# 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:
|
3. Create configuration:
|
||||||
```bash
|
```bash
|
||||||
# Create config directory
|
# Create config directory and copy template
|
||||||
mkdir -p proxmox-config
|
mkdir -p proxmox-config
|
||||||
|
|
||||||
# Copy example config
|
|
||||||
cp config/config.example.json proxmox-config/config.json
|
cp config/config.example.json proxmox-config/config.json
|
||||||
|
```
|
||||||
|
|
||||||
# Edit the config with your Proxmox details
|
4. Edit `proxmox-config/config.json`:
|
||||||
# See Configuration section below
|
```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
|
### 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
|
- 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
|
||||||
|
|
||||||
### 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
|
## 🚀 Running the Server
|
||||||
|
|
||||||
@@ -177,21 +140,61 @@ source .venv/bin/activate # Linux/macOS
|
|||||||
python -m proxmox_mcp.server
|
python -m proxmox_mcp.server
|
||||||
```
|
```
|
||||||
|
|
||||||
### Claude Desktop Integration
|
### Cline 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
|
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`):
|
||||||
mcp install proxmox_mcp/server.py \
|
|
||||||
--name "Proxmox Manager" \
|
```json
|
||||||
-v PROXMOX_HOST=your-host \
|
{
|
||||||
-v PROXMOX_USER=username@pve \
|
"mcpServers": {
|
||||||
-v PROXMOX_TOKEN_NAME=your-token \
|
"github.com/canvrno/ProxmoxMCP": {
|
||||||
-v PROXMOX_TOKEN_VALUE=your-secret
|
"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
|
# 🔧 Available Tools
|
||||||
|
|
||||||
The server provides the following MCP tools for interacting with Proxmox:
|
The server provides the following MCP tools for interacting with Proxmox:
|
||||||
@@ -354,9 +357,8 @@ proxmox-mcp/
|
|||||||
│ │ └── console/ # VM console operations
|
│ │ └── console/ # VM console operations
|
||||||
│ └── utils/ # Utilities (auth, logging)
|
│ └── utils/ # Utilities (auth, logging)
|
||||||
├── tests/ # Test suite
|
├── tests/ # Test suite
|
||||||
├── config/
|
├── proxmox-config/
|
||||||
│ └── config.example.json # Configuration template
|
│ └── config.example.json # Configuration template
|
||||||
├── ClineInstall.md # Cline-specific installation guide
|
|
||||||
├── pyproject.toml # Project metadata and dependencies
|
├── pyproject.toml # Project metadata and dependencies
|
||||||
└── LICENSE # MIT License
|
└── LICENSE # MIT License
|
||||||
```
|
```
|
||||||
|
|||||||
Reference in New Issue
Block a user