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:

{
  "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