@aidalinfo/proxmox-mcp 1.0.0

package/README.md

@@ -0,0 +1,41 @@
+# @aidalinfo/proxmox-mcp
+
+MCP server for a Proxmox VE cluster, with two modes:
+
+- **`readonly`** (default) — only read tools are exposed.
+- **`full`** — read tools **plus** write tools (VM/LXC lifecycle, snapshots, migrate).
+
+In `readonly` mode the write tools are never registered, so the model cannot call them.
+
+## Tools
+
+**Read (both modes):** `pve_version`, `pve_cluster_status`, `pve_cluster_resources`,
+`pve_nodes`, `pve_node_info`, `pve_vms`, `pve_vm_info`, `pve_containers`,
+`pve_container_info`, `pve_storage`, `pve_storage_content`, `pve_tasks`, `pve_raw_get`.
+
+**Write (`full` only):** `pve_vm_action`, `pve_lxc_action`, `pve_snapshot_create`,
+`pve_snapshot_delete`, `pve_snapshot_rollback`, `pve_migrate`.
+
+## Environment
+
+| Var | Required | Default | Role |
+|---|---|---|---|
+| `PROXMOX_HOST` | yes | — | e.g. `https://pve3.lan:8006` |
+| `PROXMOX_TOKEN_ID` | yes | — | e.g. `root@pam!ia-access` |
+| `PROXMOX_TOKEN_SECRET` | yes | — | token secret |
+| `PROXMOX_MODE` | no | `readonly` | `readonly` \| `full` |
+| `PROXMOX_TLS_INSECURE` | no | `false` | `true` to skip TLS verification (self-signed certs) |
+
+## Register with Claude Code
+
+```bash
+claude mcp add proxmox --scope user \
+  -e PROXMOX_HOST=https://pve3.lan:8006 \
+  -e PROXMOX_TOKEN_ID='root@pam!ia-access' \
+  -e PROXMOX_TOKEN_SECRET=... \
+  -e PROXMOX_MODE=readonly \
+  -e PROXMOX_TLS_INSECURE=true \
+  -- node /ABS/PATH/cloud-mcp/packages/proxmox-mcp/dist/index.js
+```
+
+For read-only use, create a token with the **PVEAuditor** role rather than `root@pam`.

package/dist/__tests__/mode-gating.test.js

@@ -0,0 +1,36 @@
+import { describe, it, expect } from "@jest/globals";
+import { registerTools, parseMode } from "../register.js";
+function fakeServer() {
+    const names = [];
+    const server = { tool: (name) => { names.push(name); } };
+    return { server, names };
+}
+const fakeClient = {};
+describe("parseMode", () => {
+    it("defaults to readonly when undefined", () => { expect(parseMode(undefined)).toBe("readonly"); });
+    it("treats unknown values as readonly", () => { expect(parseMode("banana")).toBe("readonly"); });
+    it("recognizes full", () => { expect(parseMode("full")).toBe("full"); });
+});
+describe("registerTools mode gating", () => {
+    it("readonly registers read tools but NOT write tools", () => {
+        const { server, names } = fakeServer();
+        registerTools(server, fakeClient, "readonly");
+        expect(names).toContain("pve_nodes");
+        expect(names).toContain("pve_vms");
+        expect(names).toContain("pve_raw_get");
+        expect(names).not.toContain("pve_vm_action");
+        expect(names).not.toContain("pve_snapshot_create");
+        expect(names).not.toContain("pve_migrate");
+    });
+    it("full registers read AND write tools", () => {
+        const { server, names } = fakeServer();
+        registerTools(server, fakeClient, "full");
+        expect(names).toContain("pve_nodes");
+        expect(names).toContain("pve_vm_action");
+        expect(names).toContain("pve_lxc_action");
+        expect(names).toContain("pve_snapshot_create");
+        expect(names).toContain("pve_snapshot_delete");
+        expect(names).toContain("pve_snapshot_rollback");
+        expect(names).toContain("pve_migrate");
+    });
+});

package/dist/__tests__/proxmox-client.test.js

@@ -0,0 +1,27 @@
+import { describe, it, expect } from "@jest/globals";
+import { validatePath, buildAuthHeader, ProxmoxClient } from "../proxmox-client.js";
+describe("validatePath", () => {
+    it("rejects paths containing ..", () => {
+        expect(() => validatePath("/nodes/../secret")).toThrow();
+    });
+    it("rejects paths containing #", () => {
+        expect(() => validatePath("/nodes#frag")).toThrow();
+    });
+    it("rejects relative paths", () => {
+        expect(() => validatePath("nodes")).toThrow();
+    });
+    it("accepts a normal absolute path", () => {
+        expect(() => validatePath("/cluster/resources")).not.toThrow();
+    });
+});
+describe("buildAuthHeader", () => {
+    it("formats the PVEAPIToken header exactly", () => {
+        expect(buildAuthHeader("root@pam!ia-access", "secret-uuid")).toBe("PVEAPIToken=root@pam!ia-access=secret-uuid");
+    });
+});
+describe("ProxmoxClient", () => {
+    it("composes the api2/json base URL and strips a trailing slash", () => {
+        const c = new ProxmoxClient({ host: "https://pve3.lan:8006/", tokenId: "t", tokenSecret: "s" });
+        expect(c.baseUrl).toBe("https://pve3.lan:8006/api2/json");
+    });
+});

package/dist/index.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ProxmoxClient } from "./proxmox-client.js";
+import { registerTools, parseMode } from "./register.js";
+const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
+function required(name) {
+    const val = process.env[name];
+    if (!val) {
+        process.stderr.write(`Missing required env var: ${name}\n`);
+        process.exit(1);
+    }
+    return val;
+}
+const mode = parseMode(process.env.PROXMOX_MODE);
+if (process.env.PROXMOX_TLS_INSECURE === "true") {
+    process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
+    process.stderr.write("⚠ PROXMOX_TLS_INSECURE=true — TLS certificate verification disabled\n");
+}
+const client = new ProxmoxClient({
+    host: required("PROXMOX_HOST"),
+    tokenId: required("PROXMOX_TOKEN_ID"),
+    tokenSecret: required("PROXMOX_TOKEN_SECRET"),
+});
+const server = new McpServer({ name: "proxmox", version: pkg.version });
+registerTools(server, client, mode);
+await server.connect(new StdioServerTransport());
+process.stderr.write(`proxmox-mcp v${pkg.version} ready (mode: ${mode})\n`);

package/dist/proxmox-client.js

@@ -0,0 +1,72 @@
+export const TIMEOUT_MS = 30_000;
+const FORBIDDEN_PATH_PATTERNS = /[#]|\.\./;
+export function validatePath(path) {
+    if (FORBIDDEN_PATH_PATTERNS.test(path)) {
+        throw new Error(`Unsafe API path rejected: "${path}" — must not contain ".." or "#"`);
+    }
+    if (!path.startsWith("/")) {
+        throw new Error(`API path must start with "/": "${path}"`);
+    }
+}
+export function buildAuthHeader(tokenId, tokenSecret) {
+    return `PVEAPIToken=${tokenId}=${tokenSecret}`;
+}
+export class ProxmoxClient {
+    baseUrl;
+    authHeader;
+    constructor(config) {
+        this.baseUrl = `${config.host.replace(/\/+$/, "")}/api2/json`;
+        this.authHeader = buildAuthHeader(config.tokenId, config.tokenSecret);
+    }
+    async request(method, path, opts = {}) {
+        validatePath(path);
+        let url = `${this.baseUrl}${path}`;
+        if (opts.query) {
+            const params = new URLSearchParams();
+            for (const [k, v] of Object.entries(opts.query)) {
+                if (v !== undefined && v !== null && v !== "")
+                    params.set(k, String(v));
+            }
+            const qs = params.toString();
+            if (qs)
+                url += "?" + qs;
+        }
+        const headers = {
+            Authorization: this.authHeader,
+            Accept: "application/json",
+        };
+        let body;
+        if (opts.body) {
+            const form = new URLSearchParams();
+            for (const [k, v] of Object.entries(opts.body)) {
+                if (v !== undefined && v !== null && v !== "")
+                    form.set(k, String(v));
+            }
+            body = form.toString();
+            headers["Content-Type"] = "application/x-www-form-urlencoded";
+        }
+        const res = await fetch(url, {
+            method: method.toUpperCase(),
+            headers,
+            body,
+            signal: AbortSignal.timeout(TIMEOUT_MS),
+        });
+        const text = await res.text();
+        if (!res.ok) {
+            throw new Error(`Proxmox API ${method.toUpperCase()} ${path} → ${res.status}: ${text.slice(0, 500)}`);
+        }
+        if (!text)
+            return undefined;
+        const json = JSON.parse(text);
+        return (json && typeof json === "object" && "data" in json ? json.data : json);
+    }
+    get(path, query) {
+        return this.request("GET", path, { query });
+    }
+    post(path, body) {
+        return this.request("POST", path, { body });
+    }
+    del(path) {
+        return this.request("DELETE", path);
+    }
+}

package/dist/register.js

@@ -0,0 +1,24 @@
+import { registerClusterTools } from "./tools/cluster.js";
+import { registerVmTools } from "./tools/vms.js";
+import { registerStorageTools } from "./tools/storage.js";
+import { registerTaskTools } from "./tools/tasks.js";
+import { registerRawTools } from "./tools/raw.js";
+import { registerLifecycleTools } from "./tools/lifecycle.js";
+import { registerSnapshotTools } from "./tools/snapshots.js";
+import { registerMigrateTools } from "./tools/migrate.js";
+export function parseMode(raw) {
+    return raw === "full" ? "full" : "readonly";
+}
+/** Read tools always register; write tools only in `full` mode. */
+export function registerTools(server, client, mode) {
+    registerClusterTools(server, client);
+    registerVmTools(server, client);
+    registerStorageTools(server, client);
+    registerTaskTools(server, client);
+    registerRawTools(server, client);
+    if (mode === "full") {
+        registerLifecycleTools(server, client);
+        registerSnapshotTools(server, client);
+        registerMigrateTools(server, client);
+    }
+}

package/dist/tools/cluster.js

@@ -0,0 +1,83 @@
+import { z } from "zod";
+import { textResult, errResult, fmtBytes, fmtPct, fmtUptime } from "./utils.js";
+export function registerClusterTools(server, pve) {
+    server.tool("pve_version", "Get the Proxmox VE version", {}, async () => {
+        try {
+            const v = await pve.get("/version");
+            return textResult(`# Proxmox VE\n- Version: ${v.version ?? "?"}\n- Release: ${v.release ?? "?"}\n- Repo ID: ${v.repoid ?? "?"}`);
+        }
+        catch (err) {
+            return errResult(err);
+        }
+    });
+    server.tool("pve_cluster_status", "Get cluster membership and quorum status", {}, async () => {
+        try {
+            const items = await pve.get("/cluster/status");
+            if (!items?.length)
+                return textResult("No cluster status returned (standalone node?).");
+            const lines = [`# Cluster status (${items.length})`, ""];
+            for (const e of items) {
+                if (e.type === "cluster")
+                    lines.push(`## Cluster: ${e.name ?? "?"} — quorate: ${e.quorate ? "yes" : "no"} · nodes: ${e.nodes ?? "?"}`, "");
+                else
+                    lines.push(`- node **${e.name ?? "?"}** — ${e.online ? "online" : "offline"}${e.ip ? ` · ${e.ip}` : ""}`);
+            }
+            return textResult(lines.join("\n"));
+        }
+        catch (err) {
+            return errResult(err);
+        }
+    });
+    server.tool("pve_cluster_resources", "One-shot overview of all cluster resources (VMs, nodes, storage)", { type: z.enum(["vm", "storage", "node"]).optional().describe("Filter by resource type") }, async ({ type }) => {
+        try {
+            const items = await pve.get("/cluster/resources", { type });
+            if (!items?.length)
+                return textResult("No resources found.");
+            const lines = [`# Cluster resources (${items.length})`, ""];
+            for (const r of items) {
+                if (r.type === "node")
+                    lines.push(`- [node] **${r.node}** — ${r.status ?? "?"} · CPU ${fmtPct(r.cpu)} · mem ${fmtBytes(r.mem)}/${fmtBytes(r.maxmem)}`);
+                else if (r.type === "storage")
+                    lines.push(`- [storage] **${r.storage}** @${r.node} — ${r.status ?? "?"} · ${fmtBytes(r.disk)}/${fmtBytes(r.maxdisk)}`);
+                else
+                    lines.push(`- [${r.type}] **${r.name ?? r.vmid}** (vmid ${r.vmid}) @${r.node} — ${r.status ?? "?"} · CPU ${fmtPct(r.cpu)} · mem ${fmtBytes(r.mem)}`);
+            }
+            return textResult(lines.join("\n"));
+        }
+        catch (err) {
+            return errResult(err);
+        }
+    });
+    server.tool("pve_nodes", "List all nodes in the Proxmox cluster", {}, async () => {
+        try {
+            const items = await pve.get("/nodes");
+            if (!items?.length)
+                return textResult("No nodes found.");
+            const lines = [`# Nodes (${items.length})`, ""];
+            for (const n of items)
+                lines.push(`- **${n.node}** — ${n.status ?? "?"} · CPU ${fmtPct(n.cpu)} · mem ${fmtBytes(n.mem)}/${fmtBytes(n.maxmem)} · up ${fmtUptime(n.uptime)}`);
+            return textResult(lines.join("\n"));
+        }
+        catch (err) {
+            return errResult(err);
+        }
+    });
+    server.tool("pve_node_info", "Get detailed status of one node (CPU, RAM, uptime, load)", { node: z.string().describe("Node name, e.g. pve3") }, async ({ node }) => {
+        try {
+            const s = await pve.get(`/nodes/${node}/status`);
+            const lines = [
+                `# Node: ${node}`,
+                `- PVE version: ${s.pveversion ?? "?"}`,
+                `- Uptime: ${fmtUptime(s.uptime)}`,
+                `- CPU load: ${fmtPct(s.cpu)}`,
+                `- Load avg: ${s.loadavg?.join(", ") ?? "?"}`,
+                `- Memory: ${fmtBytes(s.memory?.used)}/${fmtBytes(s.memory?.total)}`,
+                `- Root FS: ${fmtBytes(s.rootfs?.used)}/${fmtBytes(s.rootfs?.total)}`,
+            ];
+            return textResult(lines.join("\n"));
+        }
+        catch (err) {
+            return errResult(err);
+        }
+    });
+}

package/dist/tools/lifecycle.js

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import { textResult, errResult } from "./utils.js";
+const ACTIONS = ["start", "stop", "shutdown", "reboot"];
+export function registerLifecycleTools(server, pve) {
+    server.tool("pve_vm_action", "[WRITE] Change power state of a QEMU VM (start/stop/shutdown/reboot)", { node: z.string().describe("Node name"), vmid: z.number().int().describe("VM ID"), action: z.enum(ACTIONS).describe("Power action") }, async ({ node, vmid, action }) => {
+        try {
+            const upid = await pve.post(`/nodes/${node}/qemu/${vmid}/status/${action}`);
+            return textResult(`QEMU ${vmid} @${node}: ${action} requested.\nTask: ${upid}`);
+        }
+        catch (err) {
+            return errResult(err);
+        }
+    });
+    server.tool("pve_lxc_action", "[WRITE] Change power state of an LXC container (start/stop/shutdown/reboot)", { node: z.string().describe("Node name"), vmid: z.number().int().describe("Container ID"), action: z.enum(ACTIONS).describe("Power action") }, async ({ node, vmid, action }) => {
+        try {
+            const upid = await pve.post(`/nodes/${node}/lxc/${vmid}/status/${action}`);
+            return textResult(`LXC ${vmid} @${node}: ${action} requested.\nTask: ${upid}`);
+        }
+        catch (err) {
+            return errResult(err);
+        }
+    });
+}

package/dist/tools/migrate.js

@@ -0,0 +1,19 @@
+import { z } from "zod";
+import { textResult, errResult } from "./utils.js";
+export function registerMigrateTools(server, pve) {
+    server.tool("pve_migrate", "[WRITE] Migrate a VM or container to another node", {
+        node: z.string().describe("Source node"),
+        kind: z.enum(["qemu", "lxc"]).describe("Guest kind"),
+        vmid: z.number().int().describe("Guest ID"),
+        target: z.string().describe("Target node"),
+        online: z.boolean().optional().describe("Online/live migration"),
+    }, async ({ node, kind, vmid, target, online }) => {
+        try {
+            const upid = await pve.post(`/nodes/${node}/${kind}/${vmid}/migrate`, { target, online: online ? 1 : undefined });
+            return textResult(`Migration of ${kind} ${vmid} from ${node} → ${target} requested.\nTask: ${upid}`);
+        }
+        catch (err) {
+            return errResult(err);
+        }
+    });
+}

package/dist/tools/raw.js

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import { textResult, errResult } from "./utils.js";
+export function registerRawTools(server, pve) {
+    server.tool("pve_raw_get", "Perform a raw GET against any Proxmox API path under /api2/json (read-only). Example: /cluster/ha/status/current", {
+        path: z.string().describe('API path starting with "/", e.g. /nodes/pve3/qemu'),
+        query: z.record(z.string(), z.string()).optional().describe("Optional query string parameters"),
+    }, async ({ path, query }) => {
+        try {
+            const data = await pve.get(path, query);
+            return textResult("```json\n" + JSON.stringify(data, null, 2) + "\n```");
+        }
+        catch (err) {
+            return errResult(err);
+        }
+    });
+}

package/dist/tools/snapshots.js

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import { textResult, errResult } from "./utils.js";
+const KIND = ["qemu", "lxc"];
+export function registerSnapshotTools(server, pve) {
+    server.tool("pve_snapshot_create", "[WRITE] Create a snapshot of a VM or container", {
+        node: z.string().describe("Node name"),
+        kind: z.enum(KIND).describe("Guest kind"),
+        vmid: z.number().int().describe("Guest ID"),
+        snapname: z.string().describe("Snapshot name"),
+        description: z.string().optional().describe("Snapshot description"),
+    }, async ({ node, kind, vmid, snapname, description }) => {
+        try {
+            const upid = await pve.post(`/nodes/${node}/${kind}/${vmid}/snapshot`, { snapname, description });
+            return textResult(`Snapshot "${snapname}" creation requested for ${kind} ${vmid} @${node}.\nTask: ${upid}`);
+        }
+        catch (err) {
+            return errResult(err);
+        }
+    });
+    server.tool("pve_snapshot_delete", "[WRITE] Delete a snapshot of a VM or container", {
+        node: z.string().describe("Node name"),
+        kind: z.enum(KIND).describe("Guest kind"),
+        vmid: z.number().int().describe("Guest ID"),
+        snapname: z.string().describe("Snapshot name"),
+    }, async ({ node, kind, vmid, snapname }) => {
+        try {
+            const upid = await pve.del(`/nodes/${node}/${kind}/${vmid}/snapshot/${snapname}`);
+            return textResult(`Snapshot "${snapname}" deletion requested for ${kind} ${vmid} @${node}.\nTask: ${upid}`);
+        }
+        catch (err) {
+            return errResult(err);
+        }
+    });
+    server.tool("pve_snapshot_rollback", "[WRITE] Roll back a VM or container to a snapshot", {
+        node: z.string().describe("Node name"),
+        kind: z.enum(KIND).describe("Guest kind"),
+        vmid: z.number().int().describe("Guest ID"),
+        snapname: z.string().describe("Snapshot name"),
+    }, async ({ node, kind, vmid, snapname }) => {
+        try {
+            const upid = await pve.post(`/nodes/${node}/${kind}/${vmid}/snapshot/${snapname}/rollback`);
+            return textResult(`Rollback to "${snapname}" requested for ${kind} ${vmid} @${node}.\nTask: ${upid}`);
+        }
+        catch (err) {
+            return errResult(err);
+        }
+    });
+}

package/dist/tools/storage.js

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import { textResult, errResult, fmtBytes, nodeNames } from "./utils.js";
+export function registerStorageTools(server, pve) {
+    server.tool("pve_storage", "List storage datastores and their usage", { node: z.string().optional().describe("Limit to one node") }, async ({ node }) => {
+        try {
+            const nodes = await nodeNames(pve, node);
+            const out = [];
+            const failed = [];
+            for (const n of nodes) {
+                try {
+                    for (const s of (await pve.get(`/nodes/${n}/storage`)) ?? [])
+                        out.push({ ...s, node: n });
+                }
+                catch {
+                    failed.push(n);
+                }
+            }
+            if (!out.length && !failed.length)
+                return textResult("No storage found.");
+            const lines = [`# Storage (${out.length})`, ""];
+            for (const s of out)
+                lines.push(`- **${s.storage}** @${s.node} — ${s.type ?? "?"} · ${s.active ? "active" : "inactive"} · ${fmtBytes(s.used)}/${fmtBytes(s.total)} (avail ${fmtBytes(s.avail)})\n  content: ${s.content ?? "?"}`);
+            if (failed.length)
+                lines.push("", `> Note: could not query node(s): ${failed.join(", ")} (permission denied or unreachable).`);
+            return textResult(lines.join("\n"));
+        }
+        catch (err) {
+            return errResult(err);
+        }
+    });
+    server.tool("pve_storage_content", "List content of a datastore (images, backups, ISOs)", {
+        node: z.string().describe("Node name"),
+        storage: z.string().describe("Storage ID"),
+        content: z.enum(["images", "backup", "iso", "vztmpl", "rootdir", "snippets"]).optional().describe("Filter by content type"),
+    }, async ({ node, storage, content }) => {
+        try {
+            const items = await pve.get(`/nodes/${node}/storage/${storage}/content`, { content });
+            if (!items?.length)
+                return textResult(`No content in ${storage} @${node}.`);
+            const lines = [`# Content of ${storage} @${node} (${items.length})`, ""];
+            for (const c of items)
+                lines.push(`- ${c.volid} — ${c.content ?? "?"}${c.vmid ? ` · vmid ${c.vmid}` : ""} · ${fmtBytes(c.size)}${c.format ? ` · ${c.format}` : ""}`);
+            return textResult(lines.join("\n"));
+        }
+        catch (err) {
+            return errResult(err);
+        }
+    });
+}

package/dist/tools/tasks.js

@@ -0,0 +1,36 @@
+import { z } from "zod";
+import { textResult, errResult, nodeNames } from "./utils.js";
+export function registerTaskTools(server, pve) {
+    server.tool("pve_tasks", "List recent tasks (per node or whole cluster)", {
+        node: z.string().optional().describe("Limit to one node"),
+        limit: z.number().int().optional().describe("Max tasks per node (default 25)"),
+    }, async ({ node, limit }) => {
+        try {
+            const nodes = await nodeNames(pve, node);
+            const out = [];
+            const failed = [];
+            for (const n of nodes) {
+                try {
+                    for (const t of (await pve.get(`/nodes/${n}/tasks`, { limit: limit ?? 25 })) ?? [])
+                        out.push({ ...t, node: n });
+                }
+                catch {
+                    failed.push(n);
+                }
+            }
+            if (!out.length && !failed.length)
+                return textResult("No recent tasks.");
+            const lines = [`# Recent tasks (${out.length})`, ""];
+            for (const t of out) {
+                const start = t.starttime ? new Date(t.starttime * 1000).toISOString() : "?";
+                lines.push(`- [${t.status ?? "running"}] ${t.type ?? "?"}${t.id ? ` (${t.id})` : ""} @${t.node} · ${t.user ?? "?"} · ${start}`);
+            }
+            if (failed.length)
+                lines.push("", `> Note: could not query node(s): ${failed.join(", ")} (permission denied or unreachable).`);
+            return textResult(lines.join("\n"));
+        }
+        catch (err) {
+            return errResult(err);
+        }
+    });
+}

package/dist/tools/utils.js

@@ -0,0 +1,24 @@
+/** Resolve the list of node names to query: the single given node, or all cluster nodes. */
+export async function nodeNames(pve, node) {
+    if (node)
+        return [node];
+    const nodes = await pve.get("/nodes");
+    return (nodes ?? []).map((n) => n.node).filter((n) => Boolean(n));
+}
+export function textResult(text) {
+    return { content: [{ type: "text", text }] };
+}
+export function errResult(err) {
+    return {
+        content: [
+            { type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` },
+        ],
+        isError: true,
+    };
+}
+/** Bytes → "12.3 Gi". Returns "?" for null/undefined. */
+export const fmtBytes = (n) => n === undefined || n === null ? "?" : `${(n / 1024 ** 3).toFixed(1)} Gi`;
+/** Fraction (0..1) → "42%". Returns "?" for null/undefined. */
+export const fmtPct = (v) => v === undefined || v === null ? "?" : `${(v * 100).toFixed(0)}%`;
+/** Seconds → "5d 3h". Returns "?" for null/undefined. */
+export const fmtUptime = (s) => s === undefined || s === null ? "?" : `${Math.floor(s / 86400)}d ${Math.floor((s % 86400) / 3600)}h`;

package/dist/tools/vms.js

@@ -0,0 +1,100 @@
+import { z } from "zod";
+import { textResult, errResult, fmtBytes, fmtPct, fmtUptime, nodeNames } from "./utils.js";
+async function listGuests(pve, kind, node) {
+    const nodes = await nodeNames(pve, node);
+    const guests = [];
+    const failed = [];
+    for (const n of nodes) {
+        try {
+            const items = await pve.get(`/nodes/${n}/${kind}`);
+            for (const g of items ?? [])
+                guests.push({ ...g, node: n });
+        }
+        catch {
+            failed.push(n);
+        }
+    }
+    return { guests, failed };
+}
+export function registerVmTools(server, pve) {
+    server.tool("pve_vms", "List QEMU virtual machines across the cluster", { node: z.string().optional().describe("Limit to one node") }, async ({ node }) => {
+        try {
+            const { guests: vms, failed } = await listGuests(pve, "qemu", node);
+            if (!vms.length && !failed.length)
+                return textResult("No QEMU VMs found.");
+            const lines = [`# QEMU VMs (${vms.length})`, ""];
+            for (const v of vms)
+                lines.push(`- **${v.name ?? v.vmid}** (vmid ${v.vmid}) @${v.node} — ${v.status ?? "?"} · CPU ${fmtPct(v.cpu)} · mem ${fmtBytes(v.mem)}/${fmtBytes(v.maxmem)} · up ${fmtUptime(v.uptime)}`);
+            if (failed.length)
+                lines.push("", `> Note: could not query node(s): ${failed.join(", ")} (permission denied or unreachable).`);
+            return textResult(lines.join("\n"));
+        }
+        catch (err) {
+            return errResult(err);
+        }
+    });
+    server.tool("pve_vm_info", "Get config + live status of one QEMU VM", { node: z.string().describe("Node name"), vmid: z.number().int().describe("VM ID") }, async ({ node, vmid }) => {
+        try {
+            const [config, status] = await Promise.all([
+                pve.get(`/nodes/${node}/qemu/${vmid}/config`),
+                pve.get(`/nodes/${node}/qemu/${vmid}/status/current`),
+            ]);
+            const lines = [
+                `# QEMU VM ${vmid} @${node}`,
+                `- Name: ${config.name ?? "?"}`,
+                `- Status: ${status.status ?? "?"}`,
+                `- Cores: ${config.cores ?? "?"} · Memory: ${config.memory ?? "?"} MB`,
+                `- OS type: ${config.ostype ?? "?"}`,
+                "",
+                "## Full config",
+                "```json",
+                JSON.stringify(config, null, 2),
+                "```",
+            ];
+            return textResult(lines.join("\n"));
+        }
+        catch (err) {
+            return errResult(err);
+        }
+    });
+    server.tool("pve_containers", "List LXC containers across the cluster", { node: z.string().optional().describe("Limit to one node") }, async ({ node }) => {
+        try {
+            const { guests: cts, failed } = await listGuests(pve, "lxc", node);
+            if (!cts.length && !failed.length)
+                return textResult("No LXC containers found.");
+            const lines = [`# LXC containers (${cts.length})`, ""];
+            for (const c of cts)
+                lines.push(`- **${c.name ?? c.vmid}** (vmid ${c.vmid}) @${c.node} — ${c.status ?? "?"} · CPU ${fmtPct(c.cpu)} · mem ${fmtBytes(c.mem)}/${fmtBytes(c.maxmem)} · up ${fmtUptime(c.uptime)}`);
+            if (failed.length)
+                lines.push("", `> Note: could not query node(s): ${failed.join(", ")} (permission denied or unreachable).`);
+            return textResult(lines.join("\n"));
+        }
+        catch (err) {
+            return errResult(err);
+        }
+    });
+    server.tool("pve_container_info", "Get config + live status of one LXC container", { node: z.string().describe("Node name"), vmid: z.number().int().describe("Container ID") }, async ({ node, vmid }) => {
+        try {
+            const [config, status] = await Promise.all([
+                pve.get(`/nodes/${node}/lxc/${vmid}/config`),
+                pve.get(`/nodes/${node}/lxc/${vmid}/status/current`),
+            ]);
+            const lines = [
+                `# LXC container ${vmid} @${node}`,
+                `- Hostname: ${config.hostname ?? "?"}`,
+                `- Status: ${status.status ?? "?"}`,
+                `- Cores: ${config.cores ?? "?"} · Memory: ${config.memory ?? "?"} MB · Swap: ${config.swap ?? "?"} MB`,
+                `- OS template: ${config.ostype ?? "?"}`,
+                "",
+                "## Full config",
+                "```json",
+                JSON.stringify(config, null, 2),
+                "```",
+            ];
+            return textResult(lines.join("\n"));
+        }
+        catch (err) {
+            return errResult(err);
+        }
+    });
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@aidalinfo/proxmox-mcp",
+  "version": "1.0.0",
+  "description": "Proxmox VE MCP server with read-only / full-access modes — cluster, nodes, QEMU VMs, LXC, storage, backups, tasks",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "proxmox-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "author": "Killian Stein / Aidalinfo",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aidalinfo/cloud-mcp.git",
+    "directory": "packages/proxmox-mcp"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": ["mcp", "mcp-server", "proxmox", "pve", "virtualization", "qemu", "lxc", "typescript"],
+  "scripts": {
+    "build": "tsc",
+    "prepack": "npm run build",
+    "start": "node dist/index.js",
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest --passWithNoTests"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@jest/globals": "^30.3.0",
+    "@types/node": "^22.0.0",
+    "jest": "^30.3.0",
+    "ts-jest": "^29.4.6",
+    "typescript": "^5.7.0"
+  }
+}