# Proxmox MCP Server

A Model Context Protocol (MCP) server that provides comprehensive access to Proxmox VE API for complete virtualization infrastructure management. Compatible with any MCP client including Claude Desktop, Cline, and other MCP-compatible applications.

## Features

### Virtual Machine & Container Management
- List, create, start, stop, shutdown, reboot VMs and LXC containers
- Get detailed status and resource usage
- Update VM/container configurations
- Delete VMs and containers

### Snapshot Management
- Create, list, delete snapshots
- Rollback to previous snapshots
- Snapshot descriptions and metadata

### Storage Management
- List available storage locations
- Browse storage content (ISOs, templates, backups, disk images)
- Check storage capacity and usage

### Node & Cluster Operations
- List all cluster nodes
- Get node status and resource usage
- View cluster status and quorum
- Network configuration management
- Version information

### Task Monitoring
- List running and completed tasks
- Get task status and progress
- View task logs for debugging

### User & Access Management
- List users and permissions
- Manage resource pools
- View pool members and assignments

## ⚠️ Security Notice

**IMPORTANT:** This server includes enterprise-grade security features. Before deploying, please review:
- 🔒 [SECURITY.md](SECURITY.md) - Security policy and best practices
- 📖 [SECURITY_IMPLEMENTATION.md](SECURITY_IMPLEMENTATION.md) - Technical implementation details

**Key Security Features:**
- ✅ Input validation with Joi schemas (prevents injection attacks)
- ✅ Multi-tier rate limiting (prevents API abuse)
- ✅ Comprehensive audit logging (security monitoring)
- ✅ SSL verification enabled by default (prevents MITM attacks)
- ✅ Confirmation required for destructive operations
- ✅ Error message sanitization (prevents information disclosure)

**Production Requirements:**
- ✅ Always use API tokens (not passwords)
- ✅ Keep SSL verification enabled (`PROXMOX_VERIFY_SSL=true`)
- ✅ Never commit `.env` files or credentials to version control
- ✅ Keep dependencies updated with `npm audit`

## Installation

### Prerequisites
- Node.js 18 or higher
- npm or yarn
- Proxmox VE 9.x (tested and developed on version 9)
- API access credentials (API token recommended)

### Quick Setup

1. **Clone the repository:**
```bash
git clone https://github.com/yourusername/proxmox-mcp-server.git
cd proxmox-mcp-server
```

2. **Install dependencies:**
```bash
npm install
```

3. **Build the project:**
```bash
npm run build
```

4. **Test the connection (optional):**
```bash
# Set environment variables
export PROXMOX_HOST=your-proxmox-server.com
export PROXMOX_USERNAME=root
export PROXMOX_REALM=pam
export PROXMOX_TOKEN_ID=your-token-id
export PROXMOX_TOKEN_SECRET=your-token-secret
export PROXMOX_VERIFY_SSL=false

# Run the server
npm run dev
```

You should see:
```
Connected to Proxmox VE X.X-X
Proxmox MCP Server running on stdio
```

## Configuration

### Creating API Tokens in Proxmox (Recommended)

API tokens provide stateless authentication and are preferred for automation:

1. Log into Proxmox web interface
2. Navigate to **Datacenter → Permissions → API Tokens**
3. Click **Add** to create a new token
4. Configure:
   - **User**: Select your user (e.g., `root@pam`)
   - **Token ID**: Give it a name (e.g., `mcp-server`)
   - **Privilege Separation**: Uncheck for full permissions
5. Click **Add**
6. **IMPORTANT**: Copy the token secret immediately - it won't be shown again!

**Benefits of API Tokens:**
- No CSRF token required
- Stateless authentication
- Can be revoked without affecting user account
- Separate permissions per token
- No expiration like session tickets

### MCP Client Configuration

This server works with any MCP-compatible client. Add it to your client's configuration file:

#### Claude Desktop

**Location:**
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

**Configuration:**
```json
{
  "mcpServers": {
    "proxmox": {
      "command": "node",
      "args": ["/absolute/path/to/proxmox-mcp-server/dist/index.js"],
      "env": {
        "PROXMOX_HOST": "your-proxmox-server.com",
        "PROXMOX_USERNAME": "root",
        "PROXMOX_REALM": "pam",
        "PROXMOX_TOKEN_ID": "your-token-id",
        "PROXMOX_TOKEN_SECRET": "your-token-secret",
        "PROXMOX_VERIFY_SSL": "false"
      }
    }
  }
}
```

#### Cline (VSCode Extension)

Add to `.vscode/settings.json` in your project:

```json
{
  "cline.mcpServers": {
    "proxmox": {
      "command": "node",
      "args": ["/absolute/path/to/proxmox-mcp-server/dist/index.js"],
      "env": {
        "PROXMOX_HOST": "your-proxmox-server.com",
        "PROXMOX_USERNAME": "root",
        "PROXMOX_REALM": "pam",
        "PROXMOX_TOKEN_ID": "your-token-id",
        "PROXMOX_TOKEN_SECRET": "your-token-secret",
        "PROXMOX_VERIFY_SSL": "false"
      }
    }
  }
}
```

#### Other MCP Clients

Follow your client's documentation for MCP server configuration. The pattern is always:
- **command**: `node`
- **args**: Path to `dist/index.js`
- **env**: Environment variables listed below

### Environment Variables

#### Required
- `PROXMOX_HOST`: IP address or hostname of your Proxmox server
- `PROXMOX_USERNAME`: Proxmox username (usually `root`)

#### Authentication (choose one method)

**Option A: API Token (Recommended)**
- `PROXMOX_TOKEN_ID`: Your API token ID
- `PROXMOX_TOKEN_SECRET`: Your API token secret

**Option B: Password**
- `PROXMOX_PASSWORD`: Your user password

#### Optional
- `PROXMOX_PORT`: API port (default: `8006`)
- `PROXMOX_REALM`: Authentication realm (default: `pam`)
- `PROXMOX_VERIFY_SSL`: Verify SSL certificates (default: `true`)
  - ⚠️ **SECURITY:** Always use `true` in production
  - Only set to `false` for development with self-signed certificates
  - Setting to `false` makes you vulnerable to man-in-the-middle attacks

## Usage Examples

Once configured with your MCP client, you can interact with Proxmox using natural language:

```
"List all VMs in my Proxmox cluster"
"Show me the status of VM 100 on node pve1"
"Create a snapshot called 'before-update' for VM 101"
"Start VM 102"
"What's the current resource usage on node pve1?"
"List all available storage locations"
"Show me recent tasks"
```

## Available Tools

### VM & Container Management

- **`list_vms`** - List all virtual machines and containers
  - Optional filters: node, type (qemu/lxc), status
  
- **`get_vm_status`** - Get detailed status of a specific VM/container
  - Parameters: node, vmid, type
  
- **`start_vm`**, **`stop_vm`**, **`shutdown_vm`**, **`reboot_vm`** - Control VM power state
  - Parameters: node, vmid, type
  
- **`create_vm`** - Create a new virtual machine
  - Parameters: node, vmid, name, cores, memory, storage, etc.
  
- **`create_container`** - Create a new LXC container
  - Parameters: node, vmid, ostemplate, hostname, memory, etc.
  
- **`delete_vm`** - Delete a VM or container
  - Parameters: node, vmid, type
  
- **`get_vm_config`**, **`update_vm_config`** - Get or update VM configuration

### Snapshot Management

- **`list_snapshots`** - List all snapshots for a VM/container
- **`create_snapshot`** - Create a new snapshot
- **`delete_snapshot`** - Delete a snapshot
- **`rollback_snapshot`** - Rollback to a previous snapshot

### Storage Management

- **`list_storage`** - List all storage locations
- **`get_storage_content`** - List content in a storage location
  - Filter by content type: iso, vztmpl, backup, images

### Node & Cluster

- **`list_nodes`** - List all cluster nodes with resource usage
- **`get_node_status`** - Get detailed status of a specific node
- **`get_cluster_status`** - Get overall cluster status and quorum
- **`get_version`** - Get Proxmox VE version information
- **`get_network_config`** - Get network configuration for a node

### Task Management

- **`list_tasks`** - List tasks on a node
- **`get_task_status`** - Get status of a specific task
- **`get_task_log`** - Get log output of a task

### User & Access

- **`list_users`** - List all users with permissions
- **`list_pools`**, **`get_pool`** - List or get details of resource pools

## Project Structure

```
proxmox-mcp-server/
├── src/
│   ├── index.ts              # Main server entry point
│   ├── types/
│   │   └── proxmox.ts        # TypeScript type definitions
│   ├── utils/
│   │   └── proxmox-client.ts # Proxmox API client
│   └── tools/
│       ├── vm-tools.ts       # VM management tools
│       ├── snapshot-tools.ts # Snapshot tools
│       ├── storage-tools.ts  # Storage tools
│       ├── node-tools.ts     # Node/cluster tools
│       ├── task-tools.ts     # Task monitoring tools
│       └── user-tools.ts     # User/access tools
├── dist/                     # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
└── README.md
```

## Development

### Build Commands

```bash
# Build once
npm run build

# Watch mode (rebuild on changes)
npm run watch

# Run directly (builds first)
npm run dev
```

### Adding New Tools

1. Create or modify tool files in `src/tools/`
2. Follow the existing pattern for tool definitions
3. Register tools in `src/index.ts`
4. Rebuild with `npm run build`

## Troubleshooting

### Connection Issues

**Problem:** "Failed to connect to Proxmox API"
- Verify `PROXMOX_HOST` is correct and accessible
- Check firewall allows port 8006
- Ensure Proxmox API is running

**Problem:** "Authentication failed"
- Verify credentials are correct
- For API tokens: check token ID and secret match exactly
- Check realm is correct (usually 'pam' or 'pve')
- Ensure token/user has required permissions

### SSL Certificate Issues

**Problem:** "SSL certificate verification failed"
- Set `PROXMOX_VERIFY_SSL=false` for self-signed certificates
- Or install proper SSL certificates on Proxmox
- In production, use valid certificates and set `PROXMOX_VERIFY_SSL=true`

### Permission Issues

**Problem:** "Permission denied" errors
- Verify user/token has required permissions
- Check role assignments in Proxmox
- For tokens: ensure "Privilege Separation" is disabled if needed

## Security Best Practices

⚠️ **IMPORTANT:** Review [SECURITY.md](SECURITY.md) and [SECURITY_IMPLEMENTATION.md](SECURITY_IMPLEMENTATION.md) before production deployment!

### Authentication & Credentials
1. **Use API Tokens** instead of passwords for automation
   - Stateless authentication
   - Can be scoped and revoked independently
   - No session management required
2. **Set appropriate permissions** - create tokens with minimal required privileges
3. **Never commit** credentials to version control
   - Use `.env` files (already in `.gitignore`)
   - Copy `.env.example` to `.env` and fill in your values
4. **Rotate tokens** regularly (at least every 90 days)
5. **Use separate tokens** for different applications/purposes

### Network & Transport Security
6. **Enable SSL verification** in production (`PROXMOX_VERIFY_SSL=true`)
   - Default is now `true` for security
   - Only disable for development with self-signed certificates
   - Disabling SSL verification makes you vulnerable to MITM attacks
7. **Restrict network access** - use firewalls and VPNs
8. **Don't expose Proxmox API** to the public internet

### Monitoring & Auditing
9. **Monitor API usage** through Proxmox task logs
10. **Enable audit logging** for all operations
11. **Review logs regularly** for suspicious activity
12. **Set up alerts** for failed authentication attempts

### Maintenance
13. **Keep dependencies updated** - run `npm audit` regularly
14. **Review security advisories** - check GitHub Security tab
15. **Test security updates** before deploying to production
16. **Have an incident response plan** ready

### Additional Resources
- 🔒 [SECURITY.md](SECURITY.md) - Security policy and vulnerability reporting
- 📖 [SECURITY_IMPLEMENTATION.md](SECURITY_IMPLEMENTATION.md) - Technical implementation details
- 📖 [Proxmox Security Best Practices](https://pve.proxmox.com/wiki/Security)

## API Reference

For detailed Proxmox API documentation:
- https://pve.proxmox.com/wiki/Proxmox_VE_API
- https://pve.proxmox.com/pve-docs/api-viewer/

## Contributing

Contributions are welcome! Please ensure:
- Code follows TypeScript best practices
- All tools have proper input validation
- Error handling is comprehensive
- Documentation is updated

## License

MIT

## Support

For issues related to:
- **This MCP server**: Open an issue in this repository
- **Proxmox VE**: Visit https://forum.proxmox.com/
- **MCP Protocol**: Visit https://modelcontextprotocol.io/

## Security

This project has undergone a comprehensive security audit and implementation by **Bob Shell AI Assistant** (August 2026).

### Security Features Implemented
- ✅ Input validation with Joi schemas
- ✅ Multi-tier rate limiting (4 levels)
- ✅ Comprehensive audit logging with Winston
- ✅ Error message sanitization
- ✅ SSL verification enabled by default
- ✅ Confirmation required for destructive operations
- ✅ Request timeouts (30 seconds)
- ✅ Secure credential management

### Security Documentation
- 🔒 [SECURITY.md](SECURITY.md) - Security policy and best practices
- 📖 [SECURITY_IMPLEMENTATION.md](SECURITY_IMPLEMENTATION.md) - Implementation details

**Security Review Credits:** Bob Shell AI Assistant - Comprehensive security audit and implementation (August 2026)

## Changelog

### Version 1.0.0
- Initial release
- Complete VM/Container management
- Snapshot operations
- Storage management
- Node and cluster monitoring
- Task tracking
- User and pool management
- API token and password authentication support
- **Security enhancements:** Input validation, rate limiting, audit logging, error sanitization