portainer-mcp — npm wrapper for npx

Deploy portainer-mcp via npx — no manual download, no PM2, just works across platforms.

This package is also a wrapper that auto-downloads the correct binary for your platform (Linux, macOS, Windows) on install.

---

🚀 Usage via npx (Recommended)

Option 1: Direct npx (no install)

npx @lauredmarin/portainer-mcp -server https://portainer.example.com -token YOUR_TOKEN

Option 2: MCP Client Config (like Claude, Cursor, etc.)

{
  "mcpServers": {
    "portainer": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "--package=@lauredmarin/portainer-mcp",
        "portainer-mcp",
        "-server", "https://portainer.example.com",
        "-token", "YOUR_TOKEN"
      ]
    }
  }
}

Option 3: Global install

npm install -g @lauredmarin/portainer-mcp
portainer-mcp -server https://portainer.example.com -token YOUR_TOKEN

---

🐳 Legacy: Server deployment via mcp-proxy + PM2

For exposing as HTTP endpoint on a VPS:

Requirements

• Linux x86-64 (amd64)
• curl, tar
• Node.js + npm (for PM2)
• uv (installed automatically by install.sh if missing)

Quick start

git clone https://github.com/Lauredmarin/portainer-mcp-amd64.git
cd portainer-mcp-amd64
bash install.sh
cp .env.example .env   # fill in your values
pm2 start ecosystem.config.js
pm2 save && pm2 startup

Configuration (.env)

| Variable | Required | Default | Description | |---|---|---|---| | PORTAINER_SERVER | ✅ | — | Portainer URL (e.g. https://portainer.example.com) | | PORTAINER_TOKEN | ✅ | — | Portainer API token | | MCP_PORT | ❌ | 8749 | Port exposed by mcp-proxy | | PORTAINER_MCP_BIN | ❌ | ~/portainer-mcp/portainer-mcp | Path to binary | | TOOLS_YAML | ❌ | — | Path to a tools.yaml to restrict tools |

MCP endpoint (HTTP mode)

Once running, the server is available at: `` http://<your-vps-ip>:<MCP_PORT>/mcp ``

MCP client config: ``json { "mcpServers": { "portainer": { "type": "http", "url": "http://<your-vps-ip>:8749/mcp" } } } ``

---

📦 Supported Platforms

| Platform | Architecture | Status | |----------|-------------|--------| | Linux | amd64, arm64, arm | ✅ | | macOS | amd64 (Intel), arm64 (Apple Silicon) | ✅ | | Windows | amd64, arm64 | ✅ |

---

🛠️ Development

git clone https://github.com/Lauredmarin/portainer-mcp-amd64.git
cd portainer-mcp-amd64
npm install
npm run postinstall  # Downloads binary
node run.js -help

---

🔗 Links

• Original portainer-mcp: https://github.com/portainer/portainer-mcp
• NPM Package: https://www.npmjs.com/package/@lauredmarin/portainer-mcp (when published)
• Issues: https://github.com/Lauredmarin/portainer-mcp-amd64/issues

---

📄 License

MIT