{"_id":"@bakhshb/proxmox-mcp-openapi","_rev":"8-a28c5dfebda9c11cf96659ca8ad756c9","name":"@bakhshb/proxmox-mcp-openapi","dist-tags":{"latest":"1.1.1"},"versions":{"1.0.0":{"name":"@bakhshb/proxmox-mcp-openapi","version":"1.0.0","keywords":["modelcontextprotocol","mcp","proxmox"],"author":"","license":"Apache-2.0","_id":"@bakhshb/proxmox-mcp-openapi@1.0.0","maintainers":[{"name":"bakhshb","email":"bakhshb@gmail.com"}],"bin":{"proxmox-mcp":"build/index.js"},"dist":{"shasum":"a87f361a85b22ca4b3f6f6881bb2729e36639457","tarball":"https://registry.npmjs.org/@bakhshb/proxmox-mcp-openapi/-/proxmox-mcp-openapi-1.0.0.tgz","fileCount":13,"integrity":"sha512-8wvnYy0OP/Vyz1H9wp+VirmlJYbzQBtHuvSYRArlhzrzW2fUUu6fLhoiGDSJTKLV4MF+nRMvUffK4T1p2DcLsA==","signatures":[{"sig":"MEQCIHeVoxT5uep3pNcNPgjGKWpis0FIoK/TnjJeGAY9rihMAiALq4vJCbo/gb8dknqDs8t6Ou9qkIwZn3OS/PNjxBUG1A==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":47226},"main":"build/index.js","type":"module","gitHead":"4d745fb0d60185982f13f2d7bf3894ab5f03d3f1","scripts":{"dev":"tsc --watch","test":"echo \"Error: no test specified\" && exit 1","build":"npm run clean && tsc && chmod 755 build/index.js","clean":"rm -rf build","start":"node build/index.js","type-check":"tsc --noEmit"},"_npmUser":{"name":"bakhshb","email":"bakhshb@gmail.com"},"_npmVersion":"10.9.7","description":"MCP Server for Proxmox VE API","directories":{},"_nodeVersion":"22.22.2","dependencies":{"zod":"3.25.28","ssh2":"^1.17.0","axios":"^1.9.0","js-yaml":"^4.1.0","@types/ssh2":"^1.15.5","@modelcontextprotocol/sdk":"1.12.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.8.3","@types/node":"^22.15.21","@types/js-yaml":"^4.0.9"},"_npmOperationalInternal":{"tmp":"tmp/proxmox-mcp-openapi_1.0.0_1774866841615_0.21935578410287193","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@bakhshb/proxmox-mcp-openapi","version":"1.0.1","keywords":["modelcontextprotocol","mcp","proxmox"],"author":"","license":"Apache-2.0","_id":"@bakhshb/proxmox-mcp-openapi@1.0.1","maintainers":[{"name":"bakhshb","email":"bakhshb@gmail.com"}],"bin":{"proxmox-mcp":"build/index.js"},"dist":{"shasum":"d69cd4f2a573022b9667bb175b81388428de178f","tarball":"https://registry.npmjs.org/@bakhshb/proxmox-mcp-openapi/-/proxmox-mcp-openapi-1.0.1.tgz","fileCount":13,"integrity":"sha512-vA51bTFGma9oO1/7RY9JmBP/Bflwn2r6/9+u+tkMrAOeCf9loPtOc+5x5FIEfKSEunH1GLafLRtxQgQaK6PqLw==","signatures":[{"sig":"MEYCIQDWvwhPecMC2UWDsqcb9R7Zd+hlH7Kmza8PxWyI4FDZegIhANi5LbOXUxYYK1AgkTklUECI+ipCpE9fTd/KzB42f64L","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":47161},"main":"build/index.js","type":"module","gitHead":"dcf2910d5db408b1b6c252247ae9f773052ab21f","scripts":{"dev":"tsc --watch","test":"echo \"Error: no test specified\" && exit 1","build":"npm run clean && tsc && chmod 755 build/index.js","clean":"rm -rf build","start":"node build/index.js","type-check":"tsc --noEmit"},"_npmUser":{"name":"bakhshb","email":"bakhshb@gmail.com"},"_npmVersion":"10.9.7","description":"MCP Server for Proxmox VE API","directories":{},"_nodeVersion":"22.22.2","dependencies":{"zod":"3.25.28","ssh2":"^1.17.0","axios":"^1.9.0","js-yaml":"^4.1.0","@types/ssh2":"^1.15.5","@modelcontextprotocol/sdk":"1.12.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.8.3","@types/node":"^22.15.21","@types/js-yaml":"^4.0.9"},"_npmOperationalInternal":{"tmp":"tmp/proxmox-mcp-openapi_1.0.1_1774870216801_0.3911766832270289","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@bakhshb/proxmox-mcp-openapi","version":"1.0.2","keywords":["modelcontextprotocol","mcp","proxmox"],"author":"","license":"Apache-2.0","_id":"@bakhshb/proxmox-mcp-openapi@1.0.2","maintainers":[{"name":"bakhshb","email":"bakhshb@gmail.com"}],"bin":{"proxmox-mcp":"build/index.js"},"dist":{"shasum":"cc205e590c8f2c3527aeb1e1d6974e3b335fcbec","tarball":"https://registry.npmjs.org/@bakhshb/proxmox-mcp-openapi/-/proxmox-mcp-openapi-1.0.2.tgz","fileCount":14,"integrity":"sha512-V45D3bhhB4m1ATKSv3p6Oa99AAqhnQ5ftbOuKyX1Ft4anG4gN6JHODIWBmyTFXCqAuUNT89XsPGaKMg6wsInmQ==","signatures":[{"sig":"MEUCIQC7q2gEOZv4W625F1B9V8V0qSaG6pu/DzExz0XFNUZ3FQIgTvjHpyFL4Z2gYEbm+3YePPviojJPXK1Qek8SMBoFwoE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2471045},"main":"build/index.js","type":"module","gitHead":"531d745de2087d55be755917fc5813abf67fefe4","scripts":{"dev":"tsc --watch","test":"echo \"Error: no test specified\" && exit 1","build":"npm run clean && tsc && chmod 755 build/index.js","clean":"rm -rf build","start":"node build/index.js","type-check":"tsc --noEmit"},"_npmUser":{"name":"bakhshb","email":"bakhshb@gmail.com"},"_npmVersion":"10.9.7","description":"MCP Server for Proxmox VE API","directories":{},"_nodeVersion":"22.22.2","dependencies":{"zod":"3.25.28","ssh2":"^1.17.0","axios":"^1.9.0","js-yaml":"^4.1.0","@types/ssh2":"^1.15.5","@modelcontextprotocol/sdk":"1.12.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.8.3","@types/node":"^22.15.21","@types/js-yaml":"^4.0.9"},"_npmOperationalInternal":{"tmp":"tmp/proxmox-mcp-openapi_1.0.2_1774873248211_0.0040946606333038815","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@bakhshb/proxmox-mcp-openapi","version":"1.0.3","keywords":["modelcontextprotocol","mcp","proxmox"],"author":"","license":"Apache-2.0","_id":"@bakhshb/proxmox-mcp-openapi@1.0.3","maintainers":[{"name":"bakhshb","email":"bakhshb@gmail.com"}],"bin":{"proxmox-mcp":"build/index.js"},"dist":{"shasum":"fbffed038ef9bf8909cc77e506df2933b4b5aed6","tarball":"https://registry.npmjs.org/@bakhshb/proxmox-mcp-openapi/-/proxmox-mcp-openapi-1.0.3.tgz","fileCount":14,"integrity":"sha512-wGJN9wBs1NqCRxm/0n3O20jdc1oAcSwAzKCoIbukqxbqkFdoTy/1uzoU313tuy1VxDhNx/rBQIMYW5t6A3WVVA==","signatures":[{"sig":"MEUCIFG2Bcmfr215YfHty5Lw4z5ewPp3A4Ze2nXmwrMvHjOGAiEAqGhuHYx3eqadltzBBt1kH4xrgrLKUm/WkG8817B3e+E=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2472481},"main":"build/index.js","type":"module","gitHead":"7df19073baa99d63b3bd5927d78d5fc251c6aac1","scripts":{"dev":"tsc --watch","test":"echo \"Error: no test specified\" && exit 1","build":"npm run clean && tsc && chmod 755 build/index.js","clean":"rm -rf build","start":"node build/index.js","type-check":"tsc --noEmit"},"_npmUser":{"name":"bakhshb","email":"bakhshb@gmail.com"},"_npmVersion":"10.9.7","description":"MCP Server for Proxmox VE API","directories":{},"_nodeVersion":"22.22.2","dependencies":{"zod":"3.25.28","ssh2":"^1.17.0","axios":"^1.9.0","js-yaml":"^4.1.0","@types/ssh2":"^1.15.5","@modelcontextprotocol/sdk":"1.12.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.8.3","@types/node":"^22.15.21","@types/js-yaml":"^4.0.9"},"_npmOperationalInternal":{"tmp":"tmp/proxmox-mcp-openapi_1.0.3_1774875773253_0.653452299113696","host":"s3://npm-registry-packages-npm-production"}},"1.0.4":{"name":"@bakhshb/proxmox-mcp-openapi","version":"1.0.4","keywords":["modelcontextprotocol","mcp","proxmox"],"author":"","license":"Apache-2.0","_id":"@bakhshb/proxmox-mcp-openapi@1.0.4","maintainers":[{"name":"bakhshb","email":"bakhshb@gmail.com"}],"bin":{"proxmox-mcp":"build/index.js"},"dist":{"shasum":"0dd2bbbeb6c28c945f1feb0cae1f2fafc692839a","tarball":"https://registry.npmjs.org/@bakhshb/proxmox-mcp-openapi/-/proxmox-mcp-openapi-1.0.4.tgz","fileCount":14,"integrity":"sha512-PkeED5NRTPzwy5ZEDxs40rlY0pRW6QiUWX9nuheec/4SB4b2A0vD2QuXqKqyAZMISjcLKyKGS0VtWIi0+wFl8w==","signatures":[{"sig":"MEYCIQCB7VwlSf8rCYx3fBSx63U/9nYwdUXeVnSwhlbVbLhyXAIhAJCqAinrGDjQAFtP88r33RfdSE1ZyQtgnLwpQN2H+/Ay","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2472440},"main":"build/index.js","type":"module","gitHead":"70f310900dbfc14af1879a2a9a71119612e76019","scripts":{"dev":"tsc --watch","test":"echo \"Error: no test specified\" && exit 1","build":"npm run clean && tsc && chmod 755 build/index.js","clean":"rm -rf build","start":"node build/index.js","type-check":"tsc --noEmit"},"_npmUser":{"name":"bakhshb","email":"bakhshb@gmail.com"},"_npmVersion":"10.9.7","description":"MCP Server for Proxmox VE API","directories":{},"_nodeVersion":"22.22.2","dependencies":{"zod":"3.25.28","ssh2":"^1.17.0","axios":"^1.9.0","js-yaml":"^4.1.0","@types/ssh2":"^1.15.5","@modelcontextprotocol/sdk":"1.12.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.8.3","@types/node":"^22.15.21","@types/js-yaml":"^4.0.9"},"_npmOperationalInternal":{"tmp":"tmp/proxmox-mcp-openapi_1.0.4_1774876015032_0.36487326116750096","host":"s3://npm-registry-packages-npm-production"}},"1.0.5":{"name":"@bakhshb/proxmox-mcp-openapi","version":"1.0.5","keywords":["modelcontextprotocol","mcp","proxmox"],"author":"","license":"Apache-2.0","_id":"@bakhshb/proxmox-mcp-openapi@1.0.5","maintainers":[{"name":"bakhshb","email":"bakhshb@gmail.com"}],"bin":{"proxmox-mcp":"build/index.js"},"dist":{"shasum":"af1272e91bcbd0f92916054e9645eff9c59ccd73","tarball":"https://registry.npmjs.org/@bakhshb/proxmox-mcp-openapi/-/proxmox-mcp-openapi-1.0.5.tgz","fileCount":14,"integrity":"sha512-fD0tjnxJo8OlZcnUhNYHq+IofltN2IW7/6eAU1JNxxDsg7qteTKMYtz+lhc/GU3vZVNkWWiNlZUaf97yock1TA==","signatures":[{"sig":"MEUCIQCorqnNWFiLhXQ6BbbTY+SG/3eqCrJiuPHrTpeY4MMUhQIgUHCvzTnlHHKcF+Lq6pPkt4XGkSOb2nLSRUcae+WnvC8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2481698},"main":"build/index.js","type":"module","gitHead":"d8e530a5f7ef48bd2a6186ccad5322e20cdbf42a","scripts":{"dev":"tsc --watch","test":"echo \"Error: no test specified\" && exit 1","build":"npm run clean && tsc && chmod 755 build/index.js","clean":"rm -rf build","start":"node build/index.js","type-check":"tsc --noEmit"},"_npmUser":{"name":"bakhshb","email":"bakhshb@gmail.com"},"_npmVersion":"10.9.7","description":"MCP Server for Proxmox VE API","directories":{},"_nodeVersion":"22.22.2","dependencies":{"zod":"3.25.28","ssh2":"^1.17.0","axios":"^1.9.0","js-yaml":"^4.1.0","@types/ssh2":"^1.15.5","@modelcontextprotocol/sdk":"1.12.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.8.3","@types/node":"^22.15.21","@types/js-yaml":"^4.0.9"},"_npmOperationalInternal":{"tmp":"tmp/proxmox-mcp-openapi_1.0.5_1774879235586_0.7418186361963433","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@bakhshb/proxmox-mcp-openapi","version":"1.1.0","keywords":["modelcontextprotocol","mcp","proxmox"],"author":"","license":"Apache-2.0","_id":"@bakhshb/proxmox-mcp-openapi@1.1.0","maintainers":[{"name":"bakhshb","email":"bakhshb@gmail.com"}],"bin":{"proxmox-mcp":"build/index.js"},"dist":{"shasum":"ff0abb5b32075e61f75aee750ff59297501b1f80","tarball":"https://registry.npmjs.org/@bakhshb/proxmox-mcp-openapi/-/proxmox-mcp-openapi-1.1.0.tgz","fileCount":22,"integrity":"sha512-JSSIEwuhyZy5uT9iAO5QwukjUa1g9TMYYGzZ5dEFTlBJoLjiRcQz396fU5UXEF4Dwq3mS3IujdpO0w8A+KzrZQ==","signatures":[{"sig":"MEYCIQDuTIdM5H0XAP0QgHmKEFoxHmSc5BiGKpaDS0ucs77EbgIhAJz0v93rFIL6cE1Tqttr2jWudlsztajCTCkr6DFhNr2G","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2493203},"main":"build/index.js","type":"module","gitHead":"b99f06fe1a74792d5a34ea3d9b91c630f930aa15","scripts":{"dev":"tsc --watch","test":"vitest run","build":"npm run clean && tsc && chmod 755 build/index.js","clean":"rm -rf build","start":"node build/index.js","test:watch":"vitest","type-check":"tsc --noEmit"},"_npmUser":{"name":"bakhshb","email":"bakhshb@gmail.com"},"_npmVersion":"10.9.7","description":"MCP Server for Proxmox VE API","directories":{},"_nodeVersion":"22.22.2","dependencies":{"zod":"3.25.28","ssh2":"^1.17.0","axios":"^1.9.0","js-yaml":"^4.1.0","@types/ssh2":"^1.15.5","@modelcontextprotocol/sdk":"1.12.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.0.0","typescript":"^5.8.3","@types/node":"^22.15.21","@types/js-yaml":"^4.0.9","@vitest/coverage-v8":"^3.0.0"},"_npmOperationalInternal":{"tmp":"tmp/proxmox-mcp-openapi_1.1.0_1775078226133_0.19414488262122132","host":"s3://npm-registry-packages-npm-production"}},"1.1.1":{"name":"@bakhshb/proxmox-mcp-openapi","version":"1.1.1","description":"MCP Server for Proxmox VE API","main":"build/index.js","bin":{"proxmox-mcp":"build/index.js"},"scripts":{"build":"npm run clean && tsc && chmod 755 build/index.js","dev":"tsc --watch","start":"node build/index.js","type-check":"tsc --noEmit","clean":"rm -rf build","test":"vitest run","test:watch":"vitest"},"keywords":["modelcontextprotocol","mcp","proxmox"],"author":"","license":"Apache-2.0","type":"module","dependencies":{"@modelcontextprotocol/sdk":"1.12.0","@types/ssh2":"^1.15.5","axios":"^1.9.0","js-yaml":"^4.1.0","ssh2":"^1.17.0","zod":"3.25.28"},"devDependencies":{"@types/js-yaml":"^4.0.9","@types/node":"^22.15.21","@vitest/coverage-v8":"^3.0.0","typescript":"^5.8.3","vitest":"^3.0.0"},"_id":"@bakhshb/proxmox-mcp-openapi@1.1.1","gitHead":"95cbe7ba1ce9630aada5136702115dbdd10c2ea4","_nodeVersion":"22.22.2","_npmVersion":"10.9.7","dist":{"integrity":"sha512-djgKvVg9fUGHH5PaTX7/UWX3R+Z2QcfKoyUNp+a6BSwFadhnsi416zCt8nTE9xMUi+LBEvcHkBmg5quEFSp5aQ==","shasum":"f0fe595c84997d151934b2dc20a12f236dfe6bee","tarball":"https://registry.npmjs.org/@bakhshb/proxmox-mcp-openapi/-/proxmox-mcp-openapi-1.1.1.tgz","fileCount":22,"unpackedSize":2493438,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQChhnNGGVHxo2zvEfkJ9E0dFn6+agX6IR+60MEMXBHPgwIhAM7XR6z22g2QgEF+dph+eDp/hvRV+QYze2JAanmU3PcP"}]},"_npmUser":{"name":"bakhshb","email":"bakhshb@gmail.com"},"directories":{},"maintainers":[{"name":"bakhshb","email":"bakhshb@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/proxmox-mcp-openapi_1.1.1_1777305309524_0.31491270953035233"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-30T10:34:01.556Z","modified":"2026-04-27T15:55:09.814Z","1.0.0":"2026-03-30T10:34:01.817Z","1.0.1":"2026-03-30T11:30:16.948Z","1.0.2":"2026-03-30T12:20:48.421Z","1.0.3":"2026-03-30T13:02:53.467Z","1.0.4":"2026-03-30T13:06:55.172Z","1.0.5":"2026-03-30T14:00:35.861Z","1.1.0":"2026-04-01T21:17:06.367Z","1.1.1":"2026-04-27T15:55:09.713Z"},"license":"Apache-2.0","keywords":["modelcontextprotocol","mcp","proxmox"],"description":"MCP Server for Proxmox VE API","maintainers":[{"name":"bakhshb","email":"bakhshb@gmail.com"}],"readme":"# @bakhshb/proxmox-mcp-openapi\n\n[![MIT License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) **Open Source**\n\nAn **OpenAPI-driven 2-tool MCP server** for Proxmox VE. Instead of defining 35+ explicit tools, it exposes just 2 generic tools that can execute any of the 480+ Proxmox API operations dynamically — plus dedicated tools for executing commands inside VMs and containers.\n\n**Saves ~95% tokens** compared to traditional explicit-tool MCP servers.\n\n---\n\n## Tools\n\n### `proxmox-api`\nExecute any Proxmox VE API operation dynamically.\n\n| Param | Type | Required | Description |\n|-------|------|----------|-------------|\n| `path` | string | yes | API path, e.g. `/nodes/{node}/qemu/{vmid}/status/current` |\n| `method` | enum | no | HTTP method (auto-detected if omitted) |\n| `pathParams` | object | no | Path parameter values, e.g. `{\"node\": \"pve\", \"vmid\": 100}` |\n| `params` | object | no | Query params (GET) or request body (POST/PUT/PATCH) |\n\n### `proxmox-api-schema`\nDiscover available API operations from the OpenAPI spec.\n\n| Param | Type | Required | Description |\n|-------|------|----------|-------------|\n| `tag` | string | no | Filter by tag: `nodes`, `cluster`, `storage`, `access`, `pools` |\n| `path` | string | no | Get details for a specific path |\n| `method` | enum | no | Filter by HTTP method |\n\n### `proxmox-execute-container-command`\nExecute shell commands inside LXC containers via SSH + `pct exec`.\n\n> **Note:** The Proxmox REST API has no endpoint for LXC command execution. This tool SSHes to the Proxmox node and runs `pct exec` locally.\n\n| Param | Type | Required | Description |\n|-------|------|----------|-------------|\n| `node` | string | yes | Proxmox node name (e.g. `pve`) |\n| `vmid` | string\\|number | yes | Container ID (e.g. `110`) |\n| `command` | string | yes | Shell command to run inside the container |\n\n**Returns:** `{ success, exitCode, output, error, node, vmid, command }`\n\n### `proxmox-execute-vm-command`\nExecute commands inside VMs via QEMU guest agent.\n\n> **Requirements:** VM must be running with `qemu-guest-agent` installed inside the guest.\n\n| Param | Type | Required | Description |\n|-------|------|----------|-------------|\n| `node` | string | no | Proxmox node name (default: `pve`) |\n| `vmid` | number | yes | VM ID (e.g. `100`) |\n| `command` | string | yes | Single executable with args (no pipes/redirects) |\n| `timeoutMs` | number | no | Timeout in ms (default: `30000`) |\n\n**Returns:** `{ success, exitCode, output, error, outTruncated?, errTruncated? }`\n\n---\n\n## Installation\n\n### Prerequisites\n\n- **Node.js** 18+ \n- **npm** or **yarn**\n- Proxmox VE instance with API token\n- For container commands: SSH key access to Proxmox node\n\n### Option 1: Clone and Build\n\n```bash\n# Clone the repository\ngit clone https://github.com/bakhshb/proxmox-mcp-openapi.git\ncd proxmox-mcp-openapi\n\n# Install dependencies\nnpm install\n\n# Build TypeScript\nnpm run build\n```\n\n### Option 2: npm Package\n\n```bash\nnpm install -g @bakhshb/proxmox-mcp-openapi\n```\n\nThen register with your MCP client (see [MCP Client Configuration](#mcp-client-configuration)).\n\n---\n\n## Configuration\n\n### Environment Variables\n\n```bash\ncp .env.example .env\n```\n\n**Required:**\n| Variable | Description |\n|----------|-------------|\n| `PROXMOX_URL` | Base URL including `/api2/json`, e.g. `https://pve.example.com:8006/api2/json` |\n| `PROXMOX_API_TOKEN` | Token in `user@realm!tokenid=secret` format |\n\n**Optional:**\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `PROXMOX_INSECURE` | `false` | Skip TLS cert verification (for self-signed certs) |\n| `PROXMOX_TIMEOUT` | `30000` | Request timeout in ms |\n| `PROXMOX_SSH_KEY_PATH` | `~/.ssh/proxmox_mcp` | Path to SSH private key |\n| `PROXMOX_SSH_USER` | `root` | SSH username |\n| `PROXMOX_SSH_PORT` | `22` | SSH port |\n\n### Proxmox API Token Setup\n\n1. In Proxmox Web UI: **Datacenter → Permissions → API Tokens → Add**\n2. Copy the token in format: `user@realm!tokenid=secret`\n3. Assign appropriate permissions to the token (e.g. PVEAuditor for read-only, PVEEditor for modifications)\n\n### SSH Key Setup (for Container Commands)\n\n```bash\n# Generate SSH key\nssh-keygen -t ed25519 -f ~/.ssh/proxmox_mcp\n\n# Add public key to Proxmox\n# Copy: cat ~/.ssh/proxmox_mcp.pub\n# Paste in: Proxmox Web UI → Permissions → SSH Keys → Add\n```\n\n---\n\n## MCP Client Configuration\n\n### OpenClaw\n\n```json\n{\n  \"mcp\": {\n    \"servers\": {\n      \"proxmox-mcp\": {\n        \"command\": \"npx\",\n        \"args\": [\"@bakhshb/proxmox-mcp-openapi\"],\n        \"env\": {\n          \"PROXMOX_URL\": \"https://your-proxmox:8006/api2/json\",\n          \"PROXMOX_API_TOKEN\": \"root@pam!mytoken=your-secret\",\n          \"PROXMOX_INSECURE\": \"true\",\n          \"PROXMOX_SSH_KEY_PATH\": \"~/.ssh/proxmox_mcp\"\n        }\n      }\n    }\n  }\n}\n```\n\n### Claude Desktop\n\n```json\n{\n  \"mcpServers\": {\n    \"proxmox-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"@bakhshb/proxmox-mcp-openapi\"],\n      \"env\": {\n        \"PROXMOX_URL\": \"https://your-proxmox:8006/api2/json\",\n        \"PROXMOX_API_TOKEN\": \"root@pam!mytoken=your-secret\",\n        \"PROXMOX_INSECURE\": \"true\",\n        \"PROXMOX_SSH_KEY_PATH\": \"~/.ssh/proxmox_mcp\"\n      }\n    }\n  }\n}\n```\n\n### VS Code Copilot\n\nAdd the same configuration to `settings.json` under `mcp.servers`.\n\n---\n\n## Usage Examples\n\n### API Operations\n\n```javascript\n// Get VM status\nproxmox-api path=\"/nodes/pve/qemu/100/status/current\"\n\n// List all VMs\nproxmox-api path=\"/nodes/pve/qemu\"\n\n// Start a VM\nproxmox-api path=\"/nodes/pve/qemu/100/status/start\" method=POST\n\n// Get cluster resources\nproxmox-api path=\"/cluster/resources\"\n\n// Discover storage operations\nproxmox-api-schema tag=\"storage\"\n\n// Get parameters for a specific endpoint\nproxmox-api-schema path=\"/nodes/{node}/qemu/{vmid}/config\"\n```\n\n### Container Commands\n\n```javascript\n// Get OS version\nproxmox-execute-container-command node=\"pve\" vmid=110 command=\"cat /etc/os-release\"\n\n// Check hostname\nproxmox-execute-container-command node=\"pve\" vmid=110 command=\"hostname\"\n\n// Disk usage\nproxmox-execute-container-command node=\"pve\" vmid=110 command=\"df -h\"\n\n// Update packages\nproxmox-execute-container-command node=\"pve\" vmid=110 command=\"apt update && apt upgrade -y\"\n```\n\n### VM Commands\n\n```javascript\n// Simple command\nproxmox-execute-vm-command node=\"pve\" vmid=100 command=\"hostname\"\n// → { success: true, output: \"dokploy-swarm-1\" }\n\n// Check disk space (note: no flags, QEMU agent limitation)\nproxmox-execute-vm-command node=\"pve\" vmid=100 command=\"df\"\n// → { success: true, output: \"Filesystem...\" }\n\n// For shell features (pipes, redirects), use proxmox-api directly:\n// 1. POST /agent/exec with input-data for stdin\n// 2. GET /agent/exec-status?pid=<pid>\n```\n\n---\n\n## Token Savings\n\n### Comparison with Traditional MCP Architecture\n\n| MCP Server | Architecture | Tools | Token Cost |\n|------------|--------------|-------|------------|\n| **Traditional Proxmox MCP** | One tool per API operation | ~35 explicit tools | ~15,000–20,000 tokens |\n| **@bakhshb/proxmox-mcp-openapi** | OpenAPI-driven dynamic | 2 generic tools + 2 exec tools | ~500–1,000 tokens |\n\n**Result: ~95% token reduction**\n\n### Why Tokens Matter\n\nMCP servers send their tool schemas to the LLM on every request. With a 200k token context window:\n- Traditional approach: 15-20k tokens just for schema, leaving less room for actual work\n- OpenAPI-driven: ~500 tokens, leaving the context window for your data\n\n### How It Works\n\nInstead of hardcoding all tools:\n```typescript\n// Traditional: 35+ explicit tools\nserver.tool(\"list_nodes\", {...})\nserver.tool(\"get_vm_status\", {...})\nserver.tool(\"start_vm\", {...})\n// ... 30 more\n\n// OpenAPI-driven: 2 dynamic tools\nserver.tool(\"proxmox-api\", {...})           // executes any API operation\nserver.tool(\"proxmox-api-schema\", {...})    // discovers available operations\n```\n\nThe schema is loaded from the OpenAPI spec at startup, not hardcoded in the tools.\n\n---\n\n## Inspiration\n\nThis project builds on two key inspirations:\n\n1. **[ProxmoxMCP-Plus](https://github.com/bakhshb/proxmox-mcp)** — The original 35-tool Python MCP server for Proxmox VE. It proved the full API surface area but carried high token overhead.\n\n2. **[limehawk/dokploy-mcp](https://github.com/limehawk/dokploy-mcp)** — Demonstrated that a 2-tool OpenAPI-driven pattern could dramatically reduce token costs while maintaining full API coverage.\n\nThe proxmox-mcp-openapi takes the best of both: the dynamic OpenAPI approach from dokploy-mcp applied to Proxmox, with the additional SSH-based container command execution tools carried over from ProxmoxMCP-Plus.\n\n### Architecture Pattern\n\n```\nTraditional MCP:   35 tools × detailed schemas = 15k+ tokens\n                   ↓\nOpenAPI-driven:    2 tools + runtime schema loading = ~500 tokens\n                   ↓\nResult:           95% token reduction with full API coverage\n```\n\n---\n\n## Architecture\n\n- **2 core tools** + **2 execution tools**\n- **OpenAPI-driven**: 480 operations dynamically loaded from spec\n- **TypeScript**: Type-safe, compiled to JavaScript\n- **Pure REST API**: No Proxmox Perl library dependencies\n- **SSH key auth** for container commands (no API token needed for LXC exec)\n- **Exec tools carried over** from the original ProxmoxMCP-Plus (SSH+pct for LXC, QEMU agent for VMs)\n\n### OpenAPI Spec\n\nIncludes the Proxmox VE API v2 specification with 480 operations across:\n- `cluster` (122 operations)\n- `nodes` (311 operations)\n- `storage` (5 operations)\n- `access` (36 operations)\n- `pools` (5 operations)\n- `version` (1 operation)\n\n---\n\n## Troubleshooting\n\n### \"Access denied\" on container command\n1. Verify SSH key added to Proxmox Web UI → Permissions → SSH Keys\n2. Verify container is **running** (not stopped)\n3. Test SSH manually: `ssh -i ~/.ssh/proxmox_mcp root@<proxmox-host>`\n\n### \"SSH connection timeout\"\n1. Check `node` parameter is correct (use node name like `pve`, not IP)\n2. Verify SSH is running on Proxmox node\n3. Check firewall allows port 22\n\n### API returns 401/403\n1. Verify token format: `user@realm!tokenid=secret` (not just the UUID)\n2. Check token has appropriate permissions in Proxmox\n\n### VM command fails with 596\n- QEMU agent doesn't support shell features (pipes, redirects)\n- Use `proxmox-api` directly with `input-data` for stdin\n\n### VM command fails with 404\n- QEMU guest agent not installed or not running inside the VM\n- Install with: `apt install qemu-guest-agent` (Linux) or enable via Hyper-V/VMware tools\n\n---\n\n## License\n\nMIT\n","readmeFilename":"README.md"}