# portainer-mcp — npm wrapper for npx

Deploy [portainer-mcp](https://github.com/portainer/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)

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

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

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

```bash
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

```bash
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

```bash
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