# proxmox-mcp

![license](https://img.shields.io/badge/license-MIT-blue)
![status](https://img.shields.io/badge/status-active-brightgreen)
![python](https://img.shields.io/badge/python-3.8+-blue)
![proxmox](https://img.shields.io/badge/proxmox-VE-orange)
![mcp](https://img.shields.io/badge/MCP-enabled-green)
![openapi](https://img.shields.io/badge/OpenAPI-3.0-brightgreen)

> Control Proxmox VE VMs via MCP and OpenAPI

## table of contents

- [install](#install)
- [usage](#usage)
- [api](#api)
- [contributing](#contributing)
- [license](#license)

## install

```bash
pip install proxmox-mcp
```

## usage

```python
from proxmox_mcp import ProxmoxMCP

# initialize client
client = ProxmoxMCP(
    host="proxmox.example.com",
    user="root@pam",
    password="your_password"
)

# list all vms
vms = client.list_vms()
for vm in vms:
    print(f"{vm.vmid}: {vm.name} - {vm.status}")

# start a vm
client.start_vm(vmid=100)

# get vm status
status = client.get_vm_status(vmid=100)
print(f"VM 100 is {status}")

# create snapshot
client.create_snapshot(vmid=100, snapname="backup-2024")

# clone vm
client.clone_vm(vmid=100, newid=101, name="clone-vm")
```

## api

| Method | Description | Parameters |
|--------|-------------|------------|
| `list_vms()` | Get all VMs across all nodes | none |
| `get_vm_status(vmid)` | Get current VM status | `vmid: int` |
| `start_vm(vmid)` | Start a VM | `vmid: int` |
| `stop_vm(vmid)` | Stop a VM | `vmid: int` |
| `restart_vm(vmid)` | Restart a VM | `vmid: int` |
| `shutdown_vm(vmid)` | Graceful shutdown | `vmid: int` |
| `create_snapshot(vmid, snapname)` | Create VM snapshot | `vmid: int, snapname: str` |
| `delete_snapshot(vmid, snapname)` | Delete VM snapshot | `vmid: int, snapname: str` |
| `clone_vm(vmid, newid, name)` | Clone a VM | `vmid: int, newid: int, name: str` |
| `get_vm_config(vmid)` | Get VM configuration | `vmid: int` |
| `update_vm_config(vmid, config)` | Update VM settings | `vmid: int, config: dict` |

### MCP integration

The library exposes Proxmox operations through the Model Context Protocol, allowing AI assistants to manage VMs directly.

```python
# mcp server mode
from proxmox_mcp.server import run_mcp_server

run_mcp_server(
    host="proxmox.example.com",
    user="root@pam",
    password="your_password",
    port=8080
)
```

### OpenAPI schema

OpenAPI 3.0 spec available at `/openapi.json` when running in server mode. Import into tools like Postman or generate clients in other languages.

## contributing

prs welcome. open an issue first for big changes.

## license

MIT

<!-- fixme later -->

<!-- wip -->
<!-- fix nit -->