MCP Proxmox MVP - Proxmox Server Monitoring & Basic Commands

[drmfar]

Problem Statement

We need to build an MCP (Model Context Protocol) server for Proxmox VE that enables AI agents to monitor server status, access logs, and execute basic commands. This is an MVP focused on core monitoring and lifecycle management capabilities.

Solution

Build a TypeScript/Node.js MCP server that connects to Proxmox VE via API token authentication, exposing tools for monitoring and basic VM/CT lifecycle management. The server will use stdio transport and be distributed as an npm package.

User Stories

Monitoring - VM/CT Status

1. As a user, I want to list all VMs and containers on my Proxmox node, so that I can see what is running
2. As a user, I want to get the status of a specific VM/container, so that I can check if it is running, stopped, or paused
3. As a user, I want to get detailed VM/container information (CPU, memory, disk usage), so that I can monitor resource consumption

Monitoring - Node Status

4. As a user, I want to list all Proxmox nodes in my cluster, so that I can see the cluster topology
5. As a user, I want to get CPU, memory, and disk usage of a node, so that I can monitor node health
6. As a user, I want to get node uptime and version information, so that I can track maintenance windows

Monitoring - Storage Status

7. As a user, I want to list all storage pools, so that I can see available storage
8. As a user, I want to get storage usage statistics, so that I can monitor disk space
9. As a user, I want to get storage type and status information, so that I can identify storage health issues

Monitoring - Network Status

10. As a user, I want to list network interfaces on a node, so that I can see network configuration
11. As a user, I want to get network interface statistics (traffic, errors), so that I can monitor network health
12. As a user, I want to get bridge and VLAN information, so that I can understand network topology

Log Access

13. As a user, I want to read VM/container console output, so that I can debug issues
14. As a user, I want to access task logs (backup, migration, etc.), so that I can track operations
15. As a user, I want to access Proxmox system logs, so that I can monitor host health
16. As a user, I want to filter logs by time range or severity, so that I can find relevant entries

Basic Commands - VM/CT Lifecycle

17. As a user, I want to start a VM/container, so that I can bring services online
18. As a user, I want to stop a VM/container, so that I can take it offline gracefully
19. As a user, I want to shutdown a VM/container (ACPI), so that I can perform graceful shutdown
20. As a user, I want to reboot a VM/container, so that I can apply updates
21. As a user, I want to get the status after a lifecycle operation, so that I can confirm the action succeeded

Security & Access Control

22. As a user, I want to configure API token authentication via environment variables, so that credentials are secure
23. As a user, I want separate read-only and read-write access tiers, so that I can control what operations are allowed
24. As a user, I want configurable TLS verification, so that I can use self-signed certs in dev

Installation & Configuration

25. As a user, I want to install the MCP server via npm, so that I can easily add it to my project
26. As a user, I want clear configuration instructions, so that I can set up the server quickly
27. As a user, I want the server to validate configuration on startup, so that I get clear error messages

Implementation Decisions

Tech Stack

• Language: TypeScript/Node.js (ESM modules)
• Runtime: Node.js 20+ LTS
• MCP SDK: @modelcontextprotocol/server@^2.0.0 (v2 stable line)
• Schema Validation: Zod v4
• Transport: stdio (default for local MCP servers)

Proxmox Integration

• API Access: Raw HTTP client (not using proxmox-api library due to GPL-3.0 license and dormancy)
• Authentication: API token only (Authorization: PVEAPIToken=USER@REALM!TOKENID=UUID)
• Base URL: https://host:8006/api2/json/...
• TLS Handling: Default strict, allow PVE_TLS_REJECT_UNAUTHORIZED=false env var for dev

Tool Organization

• Tools organized by resource type: VM/CT, Node, Storage, Network, Logs
• Clear naming convention: {action}_{resource} (e.g., list_vms, get_node_status)
• Access tiers: read-only tools vs lifecycle/write tools

Access Tiers

• Read tier: All monitoring and log access tools
• Write tier: VM/CT lifecycle commands (start, stop, shutdown, reboot)

Environment Variables

• PVE_HOST — Proxmox server hostname/IP
• PVE_PORT — Proxmox API port (default: 8006)
• PVE_TOKEN_ID — API token ID
• PVE_TOKEN_SECRET — API token secret
• PVE_REALM — Authentication realm (default: pam)
• PVE_USERNAME — API token username
• PVE_TLS_REJECT_UNAUTHORIZED — TLS verification (default: true)

Package Structure

• Package name: @drmfar/mcp-proxmox
• Entry point: dist/index.js
• TypeScript compilation to dist/ directory

Testing Decisions

• Unit tests for each tool handler
• Integration tests against a mock Proxmox API (or real PVE in CI)
• Test external behavior (tool outputs), not implementation details
• Use vitest as the test framework
• Test both access tiers separately

Out of Scope

• Snapshot management (can be added later)
• Backup operations (can be added later)
• VM/container creation/deletion (can be added later)
• Complex networking configuration
• Cluster management operations
• HTTP/SSE transport (stdio only for MVP)

Further Notes

• Reference implementation: @samik081/mcp-pve (117 tools) - good blueprint to learn from
• Proxmox REST API documentation: https://pve.proxmox.com/pve-docs/api-viewer/
• MCP v2 spec: https://modelcontextprotocol.io/specification/2026-07-28
• Self-signed certs are common in Proxmox - TLS handling is critical

[github-actions]

This issue does not fully meet our contributing guidelines.

What needs to be fixed:

• The issue does not use one of the required issue templates (Bug Report, Feature Request, or Question).
• If this is a Feature Request, the title must start with [FEATURE]: and must include the required verification checkbox confirming the feature does not already exist.
• The issue reads as a detailed AI-generated implementation specification rather than a genuine user-facing request. Long AI-generated walls of text are not acceptable per our guidelines.
• It is also unclear how this relates to the opencode project itself — requests to build third-party MCP servers for external tools (e.g., Proxmox) are out of scope for this repository.

Please edit this issue to address the above within 2 hours, or it will be automatically closed.

If you believe this was flagged incorrectly, please let a maintainer know.

[github-actions]

This issue has been automatically closed because it was not updated to meet our contributing guidelines within the 2-hour window.

Feel free to open a new issue that follows our issue templates.