# portainer-mcp (offiziell) — BF

Überblick über die Docker-Landschaft via Portainer. Übersicht aller MCPs: [../INVENTORY.md](../INVENTORY.md).

## Ist-Stand (2026-08-28)
- **Portainer-Server läuft** auf `https://10.40.20.126:9443` (Docker-LXC auf pve, VLAN20), **v2.40.0**, managed **5 Endpoints**:
  `pve` (lokal, Id 2), `nas-bf (ds923+)` (Id 14), `macmini` (Id 20), `nas-fm (ds415+)` (Id 21), `odroid-m1` (nicht mehr im Inventar — falls noch aktiv, neu hinzufügen).
- **API-Token** in `mcp/portainer/.env` (gitignored).
- **Versions-Drift**: Portainer ist 2.40.0, das offizielle `portainer/portainer-mcp`-Image verlangt 2.42.x → **Portainer-Bump zuerst**, dann MCP-Deploy.
- **API-Token** vorhanden (admin) → in `.env` (gitignored).
- **Blocker:** `portainer-mcp` gibt es nur als **2.41.x / 2.42.x**, jeweils = gleiche Portainer-Minor.
  **2.40 hat keinen passenden MCP** → Portainer auf `.126` auf **2.42.x** bumpen (sauberster Weg).

## Weg A — lokal stdio via uvx (least-invasive, kein Portainer-Touch nötig zum Probieren)
Voraussetzung: `uv` installieren (`brew install uv` oder `curl -LsSf https://astral.sh/uv/install.sh | sh`).
```
# NACH Portainer-Bump auf 2.42 (oder Versuch 2.41 gegen 2.40):
claude mcp add portainer -s user \
  -e PORTAINER_URL=https://10.40.20.126:9443 \
  -e PORTAINER_API_KEY=ptr_... \
  -e PORTAINER_TLS_VERIFY=0 \
  -- uvx --from "mcp-portainer~=2.42.0" mcp-portainer
```
Read-only erzwingen: über MCP-Config/Profil (siehe portainer-mcp `docs/configuration.md` → „read-only capabilities").

## Weg B — Container auf DS923 (`.181:3000/mcp`), Stack-YML gitignored
**Voraussetzung:** Portainer-Bump 2.40.0 → 2.42.x (offizielles `portainer/portainer-mcp`-Image verlangt gleiche Minor).
```
# Stack deployen (gitignored): docs/nas-vlan20/stacks/portainer-mcp.yml
# Container-IP = 10.40.20.181 im vlan20-Netz (analog pve-mcp .173, komodo-mcp .176, shelly-mcp .180)
```
**Client:**
```jsonc
// ~/.claude.json + ~/.config/opencode/opencode.jsonc:
"portainer-mcp": {
  "type": "remote",
  "url": "http://10.40.20.181:3000/mcp",
  "headers": {}
}
```
Aktuell `enabled: false` bis Deploy durch ist.

## Versions-Policy (Doku)
Match MCP-Minor = Portainer-Minor. Tabelle: nur 2.41.x↔2.41.x, 2.42.x↔2.42.x. Kein 2.40.
TLS: self-signed → `PORTAINER_TLS_VERIFY=0`.