npm-mcp

Model Context Protocol server for Nginx Proxy Manager

Manage reverse-proxy routing, TLS certificates, access lists, and stream forwards conversationally — with guardrails that assume you will eventually point it at production.

Contents

• Why this exists

• How it works

• Quick start

• Authentication

• Tool catalog

• Safety model

• Configuration

• Deployment

• Testing

• Design notes

Related MCP server: npm-mcp

Why this exists

Nginx Proxy Manager has a full REST API and no MCP server. This is that server — but the interesting part isn't the plumbing, it's the constraints.

A reverse proxy is a single point of failure for everything behind it. An agent with write access to one can take down services it was never asked to touch. So the design starts from that:

Tools are generated from the API's own OpenAPI document, not hand-written. The document is pinned in-tree, and a drift test fails CI if the upstream surface changes — instead of tools silently 404-ing at runtime.

Every result crosses one redaction boundary that fails closed. It raises on anything it can't inspect rather than passing it through.

Guardrails are mutation-tested. Every safety control has a test proven to go red when the control is disabled.

How it works

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 signatures are built from the pinned document at import time, so create_proxy_host exposes 18 typed arguments with real enums — not an opaque **kwargs passthrough.

Quick start

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 serves at /mcp. A trailing slash 307-redirects, which some clients mishandle — don't let a proxy rewrite the path.

Authentication

Two layers, easy to conflate:

NPM issues no long-lived API keys, which is why the server holds credentials rather than accepting a token.

Tool catalog

66 tools = 65 API operations + get_guidance.

Names derive from the OpenAPI operationId, so list operations are get_*, not list_*.

• No pagination exists. Not one endpoint accepts limit/offset. Tools accept them and slice client-side; the tool descriptions say so.

• expand is a per-endpoint enum, not a passthrough — proxy-hosts takes access_list,owner,certificate; certificates take only owner. Out-of-enum values are rejected before the request is sent.

Safety model

• S1 matches ANY protected domain, not ALL. ALL would let the guardrail be disarmed through the tools it guards: add one unrelated domain to a host and protection evaporates.

• S1 covers update, not just delete/disable. Otherwise you strip the protected name out of domain_names, then delete cleanly — same outage.

• S1 matches on current upstream state, never the submitted body. Checking the request would let the strip-then-update path walk straight through.

• S1 wildcards match in both directions. NPM_PROTECTED_DOMAINS=*.example.net must protect app.example.net. It once matched nothing and suppressed the "unprotected" warning, because the value was explicitly set.

• S2 scopes by HTTP method, not name prefix. A delete_* rule misses disable_user_2fa — a DELETE that strips someone's second factor.

• S6 is a rule, not a list. An enumerated version silently omitted update_user, so the latch stayed shut while is_disabled: true locked out an admin.

• S7 has no override. A server that can delete its own credentials locks itself out permanently.

Configuration

Deployment

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

The container joins an existing Docker network alongside NPM and publishes no ports. NPM reaches it by container DNS and terminates TLS, so the Bearer token never crosses the wire in plaintext.

• No build: key in the compose file. A compose-string deploy (Portainer, for one) ships no build context, so the image is built first and referenced by tag.

• The healthcheck resolves the bind host instead of hardcoding 127.0.0.1. With a custom NPM_MCP_HTTP_HOST the naive version marks a perfectly healthy container as unhealthy forever. It also short-circuits under stdio, where nothing is listening at all.

• The authenticating warm-up runs in the server lifespan, so a misconfiguration fails the healthcheck rather than coming up green and breaking on first use.

Testing

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

Roughly 4,700 lines of tests against 3,300 lines of source, but the count matters less than the shape:

• 🧬 Mutation-verified guardrails — every safety control has a test proven to fail when the control is disabled. Written after discovering an asyncio.Lock whose removal kept the suite green.

• 🌐 Zero network access — every upstream call is respx-mocked. A test that needs the network is a broken test.

• 🔍 A7 sweep — all 65 tools are called against an upstream returning secrets at four nesting depths, with a negative control asserting the fixture really contains them, so the sweep can't pass vacuously.

• 📐 Schema drift guard — operation counts, payload shapes, and the packaged data file are all asserted, so an upstream upgrade fails here rather than in production.

Design notes