diff --git a/ClineInstall.md b/ClineInstall.md deleted file mode 100644 index 6a7047e..0000000 --- a/ClineInstall.md +++ /dev/null @@ -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"} -) diff --git a/README.md b/README.md index 2f6a8ec..9261ac5 100644 --- a/README.md +++ b/README.md @@ -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 + + git clone https://github.com/canvrno/ProxmoxMCP.git + cd ProxmoxMCP - # Windows (PowerShell) - python -m venv .venv - .\.venv\Scripts\Activate.ps1 + # 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 ``` diff --git a/config/config.example.json b/proxmox-config/config.example.json similarity index 100% rename from config/config.example.json rename to proxmox-config/config.example.json