npm-mcp

Model Context Protocol-Server für Nginx Proxy Manager

Verwalten Sie Reverse-Proxy-Routing, TLS-Zertifikate, Zugriffslisten und Stream-Weiterleitungen im Dialog – mit Leitplanken, die davon ausgehen, dass Sie es letztendlich auf die Produktion ausrichten werden.

Inhalt

• Warum es das gibt

• So funktioniert es

• Schnellstart

• Authentifizierung

• Tool-Katalog

• Sicherheitsmodell

• Konfiguration

• Bereitstellung

• Tests

• Design-Hinweise

Related MCP server: npm-mcp

Warum es das gibt

Nginx Proxy Manager hat eine vollständige REST-API und keinen MCP-Server. Dies ist genau dieser Server – aber der interessante Teil ist nicht die technische Infrastruktur, sondern die Beschränkungen.

Ein Reverse-Proxy ist ein Single Point of Failure für alles dahinter. Ein Agent mit Schreibzugriff auf einen solchen kann Dienste lahmlegen, die er nie anfassen sollte. Das Design beginnt also genau dort:

Tools werden aus dem OpenAPI-Dokument der API selbst generiert, nicht handgeschrieben. Das Dokument ist im Repository festgeschrieben, und ein Drift-Test lässt die CI fehlschlagen, wenn sich die Upstream-Oberfläche ändert – statt dass Tools zur Laufzeit still 404 liefern.

Jedes Ergebnis durchläuft eine Schwärzungsgrenze, die im Zweifel blockiert. Sie wirft bei allem, was sie nicht prüfen kann, einen Fehler, statt es durchzureichen.

Leitplanken sind mutationsgetestet. Jede Sicherheitskontrolle hat einen Test, der nachweislich rot wird, wenn die Kontrolle deaktiviert ist.

So funktioniert es

flowchart LR
    C["MCP Client"] -->|"Bearer (optional)"| S

    subgraph S["npm-mcp"]
        direction TB
        A["Bearer verifier<br/><i>hmac.compare_digest</i>"] --> G["Guardrails<br/><i>S1 · S2 · S6 · S7 · S8</i>"]
        G --> T["66 generated tools"]
        T --> R["serialize_result()<br/><i>redact + cap</i>"]
    end

    S -->|"JWT, auto-refreshed"| N["Nginx Proxy Manager"]
    P["npm-openapi.json<br/><i>pinned, in-package</i>"] -.->|generates| T

Tool-Signaturen werden beim Import aus dem festgeschriebenen Dokument erzeugt, daher bietet create_proxy_host 18 typisierte Argumente mit echten Enums – kein undurchsichtiger **kwargs-Durchgriff.

Schnellstart

uv sync
cp .env.example .env    # then fill in NPM_URL / NPM_IDENTITY / NPM_SECRET
uv run npm-mcp

{
  "mcpServers": {
    "npm": {
      "command": "uv",
      "args": ["run", "npm-mcp"],
      "env": {
        "NPM_URL": "https://nginx-proxy-manager.example.net",
        "NPM_IDENTITY": "npm-mcp@example.net",
        "NPM_SECRET": "…",
        "NPM_MCP_TRANSPORT": "stdio"
      }
    }
  }
}

{
  "mcpServers": {
    "npm": {
      "type": "http",
      "url": "https://npm-mcp.example.net/mcp",
      "headers": { "Authorization": "Bearer <NPM_MCP_BEARER_TOKEN>" }
    }
  }
}

FastMCP bedient unter /mcp. Ein abschließender Schrägstrich erzeugt eine 307-Weiterleitung, was einige Clients falsch behandeln – lassen Sie nicht zu, dass ein Proxy den Pfad umschreibt.

[!TIP] Rufen Sie zuerst get_guidance auf. Es meldet Antwortstrukturen, die Unterscheidung zwischen Deaktivieren und Löschen, welche Verriegelungen derzeit offen sind und die aktive Liste geschützter Domains.

Authentifizierung

Zwei Ebenen, die leicht zu verwechseln sind:

NPM vergibt keine langlebigen API-Schlüssel; deshalb hält der Server Zugangsdaten, statt ein Token zu akzeptieren.

[!IMPORTANT] POST /tokens hat zwei mögliche Antworten: ein Token oder eine 2FA-Herausforderung. Wenn das Konto 2FA aktiviert hat, setzen Sie NPM_TOTP_SECRET – andernfalls schlägt der Server beim Start fehl und benennt beide Abhilfen, statt gesund hochzufahren und beim ersten Tool-Aufruf zu brechen.

Tool-Katalog

66 Tools = 65 API-Operationen + get_guidance.

Die Namen leiten sich aus der OpenAPI-operationId ab, daher sind Listenoperationen get_* und nicht list_*.

[!WARNING] Drei Operationen sind bewusst nicht exponiert: requestToken, refreshToken, loginWith2FA. Sie sind die eigene Auth-Infrastruktur des Servers, und requestToken akzeptiert eine beliebige Identität und ein beliebiges Geheimnis – es zu registrieren würde diesen Server in ein Orakel zum Testen von Zugangsdaten gegen NPM verwandeln, mit jedem Versuch, der dem Dienstkonto zugeschrieben würde.

• Es gibt keine Paginierung. Kein einziger Endpunkt akzeptiert limit/offset. Die Tools akzeptieren sie und schneiden clientseitig; die Tool-Beschreibungen sagen das.

• expand ist ein Pro-Endpunkt-Enum, kein Durchgriff – Proxy-Hosts akzeptiert access_list,owner,certificate; Zertifikate nur owner. Werte außerhalb des Enums werden abgelehnt, bevor die Anfrage gesendet wird.

Sicherheitsmodell

[!CAUTION] Schreibvorgänge sind standardmäßig aktiviert. Dieser Server kann die Routing-Tabelle für jeden Dienst hinter dem Proxy neu schreiben. Setzen Sie NPM_READ_ONLY=1, um alle Mutationen zu deaktivieren.

• S1 matcht JEDE geschützte Domain, nicht ALLE. ALLE würde es erlauben, die Leitplanke durch die Tools, die sie schützt, zu entwaffnen: Fügen Sie einem Host eine unzusammenhängende Domain hinzu, und der Schutz verpufft.

• S1 deckt update ab, nicht nur delete/disable. Sonst entfernen Sie den geschützten Namen aus domain_names und löschen dann sauber – gleiche Störung.

• S1 matcht auf den aktuellen Upstream-Zustand, niemals auf den übermittelten Body. Würde die Anfrage geprüft, könnte der Strip-then-Update-Pfad direkt durchlaufen.

• S1-Wildcards matchen in beide Richtungen. NPM_PROTECTED_DOMAINS=*.example.net muss app.example.net schützen. Es matchte einmal nichts und unterdrückte die Warnung „ungeschützt“, weil der Wert explizit gesetzt war.

• S2 wird über die HTTP-Methode eingegrenzt, nicht über ein Namenspräfix. Eine delete_*-Regel übersieht disable_user_2fa – ein DELETE, das jemandem den zweiten Faktor entzieht.

• S6 ist eine Regel, keine Liste. Eine aufgezählte Version ließ update_user stillschweigend aus, sodass die Verriegelung geschlossen blieb, während is_disabled: true einen Admin aussperrte.

• S7 hat keine Überschreibung. Ein Server, der seine eigenen Zugangsdaten löschen kann, sperrt sich dauerhaft aus.

Konfiguration

Deployment

docker build -t npm-mcp:latest .
docker compose up -d

Der Container tritt einem vorhandenen Docker-Netzwerk neben NPM bei und veröffentlicht keine Ports. NPM erreicht ihn über den Container-DNS und terminiert TLS, sodass das Bearer-Token niemals im Klartext über die Leitung geht.

• Kein build:-Schlüssel in der Compose-Datei. Ein Compose-String-Deployment (z. B. Portainer) liefert keinen Build-Kontext mit. Das Image wird deshalb zuerst gebaut und über ein Tag referenziert.

• Der Healthcheck löst den Bind-Host auf, statt 127.0.0.1 hartzukodieren. Mit einem benutzerdefinierten NPM_MCP_HTTP_HOST markiert die naive Variante einen völlig gesunden Container für immer als ungesund. Unter stdio schlägt sie zusätzlich fehl, da dort überhaupt nichts lauscht.

• Die authentifizierende Aufwärmphase läuft in der Serverlebensdauer. So führt eine Fehlkonfiguration zu einem fehlgeschlagenen Healthcheck, statt dass der Container grün wird und erst bei der ersten Verwendung bricht.

Testing

uv run pytest              # 420 tests
uv run ruff check
uv run ruff format --check

Rund 4.700 Zeilen Tests gegenüber 3.300 Zeilen Quellcode – aber die bloße Anzahl zählt weniger als die Struktur:

• 🧬 Mutationsverifizierte Schutzvorkehrungen – für jede Sicherheitsabschirmung existiert ein Test, der nachweislich fehlschlägt, wenn die Absicherung abgeschaltet ist. Entstanden nach der Entdeckung eines asyncio.Lock, dessen Entfernung die Testsuite grün ließ.

• 🌐 Null Netzwerkzugriff – jeder Upstream-Aufruf ist mit respx gemockt. Ein Test, der das Netzwerk braucht, ist ein kaputter Test.

• 🔍 A7-Sweep – alle 65 Werkzeuge werden gegen einen Upstream aufgerufen, der Geheimnisse in vier Verschachtelungsebenen liefert; eine Negativkontrolle sichert ab, dass das Fixture diese Geheimnisse wirklich enthält, sodass der Sweep nicht ins Leere laufen kann.

• 📐 Schema-Drifit-Schutz – Operationszahlen, Payload-Strukturen und die eingepackte Datendatei werden alle überprüft; dadurch scheitert ein Upstream-Upgrade hier statt in der Produktion.

Designhinweise