proxmox-mcp-custom/IMPLEMENTATION.md

Custom Proxmox MCP Server Implementation

Architecture Overview

This project implements a Model Context Protocol (MCP) server for Proxmox VE using a "Hybrid" design pattern. It combines specific, high-value tools with raw API access to ensure both usability and comprehensive coverage.

Core Components

1. Transport:

   • Protocol: Server-Sent Events (SSE) over HTTP.
   • Framework: mcp (official Python SDK) using FastMCP.
   • Server: uvicorn (ASGI server).
   • Host Binding: 0.0.0.0:8000 (exposed for Docker).

2. Proxmox Integration:

   • Client Library: proxmoxer (Python wrapper for Proxmox API).
   • Authentication: API Token (user@pam!token_id) or Username/Password.
   • SSL: Configurable verification (default false for homelabs).

3. Deployment:

   • Container: Docker (multi-stage build with uv).
   • Registry: Gitea Container Registry (gitea.ext.ben.io).
   • Orchestration: Portainer (Docker Compose stack).
   • CI/CD: Gitea Actions (build & push on commit).

The Hybrid Tool Strategy

Instead of wrapping every Proxmox API endpoint (of which there are hundreds), we expose two layers of tools:

Layer 1: Curated Tools (High Frequency)

These tools simplify common tasks for the LLM.

• list_nodes(): Returns cluster node status.
• get_cluster_resources(): Returns all VMs, LXCs, and storage.

Layer 2: Raw Access (The "Escape Hatch")

• proxmox_api_call(path, method, data): A generic tool that allows the LLM to construct any API call supported by proxmoxer.
  • Example: path="nodes/pve1/qemu/100/status/start", method="POST"
  • Benefit: Zero maintenance. If Proxmox adds a feature, the LLM can use it immediately without code changes.

Current Implementation Details

server.py

• Uses mcp.server.fastmcp.FastMCP to define the server and tools.
• Connects to Proxmox using proxmoxer.ProxmoxAPI.
• Exposes mcp.sse_app to uvicorn for execution.

Challenges & Workarounds

• Host Header Validation: The mcp SDK enforces strict Host header checks by default. We are currently configuring FastMCP settings to allow external access (e.g., proxmox-mcp.ext.ben.io).
• Dependency Management: We use uv for fast, reliable builds in Docker.
• API Client: proxmoxer requires requests (added to pyproject.toml).

Next Steps

1. Resolve the Invalid Host header error by correctly configuring mcp.settings.allowed_hosts or middleware.
2. Deploy the final image to Portainer.
3. Connect Gemini CLI via https://proxmox-mcp.ext.ben.io/sse.

Local Testing Challenges

A significant challenge in this development environment is the lack of direct local testing capabilities. Due to the nature of operating within a sandboxed agent and the separation between the development VM (where this agent runs) and the target Docker/Portainer host, the standard iterative development loop (code -> test -> debug) is heavily impacted:

• No Direct uvicorn Execution: I cannot directly run the Python server locally to quickly test changes.
• Remote Docker Environment: Each code change requires:
  1. Committing and pushing to Gitea.
  2. Waiting for Gitea Actions to build and push the Docker image.
  3. Redeploying the Docker stack on the Portainer host.
  4. Analyzing remote container logs for feedback.
• Limited Debugging: The inability to attach a debugger or inspect live execution locally forces a heavy reliance on log analysis.
• Slow Feedback Loop: This multi-step remote process introduces significant delays, prolonging the time it takes to identify and fix issues (as evidenced by the numerous iterations for portainer-mcp and proxmox-mcp-custom).

This necessitates careful reasoning, documentation review, and a systematic approach to debugging, often leading to more turns than would be typical in a local development setup.