Nginx Proxy Manager MCP server

Nginx Proxy Manager MCP

<!-- mcp-name: io.github.euisuh/nginx-proxy-manager-mcp -->

An MCP server for Nginx Proxy Manager. It lets Claude and other MCP clients manage reverse-proxy hosts, Let's Encrypt certificates, and access lists through typed tools instead of clicking through the NPM admin UI.

"Point blog.example.com at the container on port 3000 with HTTPS"
      │
      ▼
Claude / MCP client ──► Nginx Proxy Manager MCP ──HTTP + JWT──► NPM API

The demo calls createproxyhostwithletsencrypt(dry_run=True) against a mocked NPM API and prints both request previews. No real NPM instance or credentials are used. To record it again, install the development dependencies and VHS, then run vhs docs/demo.tape from the repository root; docs/demo.py uses the same respx mocking approach as the tests.

Why this exists

Reverse-proxy changes are repetitive homelab work: create a host, point it at a container, attach a certificate, maybe restrict it to an access list. That is exactly the kind of operational task an AI assistant can handle well when it has narrow, typed tools and a local admin boundary.

This server runs either:

• as an SSE Docker sidecar next to an existing NPM container, or
• as a stdio MCP server for local clients.

Features

• 30 MCP tools for common NPM operations.
• dry_run on all mutating tools to preview NPM requests before applying them;
• One-shot createproxyhostwithletsencrypt requests a certificate, then creates an HTTPS-forced proxy host.
• JWT auth against the NPM API with in-memory token caching and automatic re-authentication on 401.
• Docker sidecar deployment that binds the MCP port to localhost by default.
• Offline pytest suite with mocked NPM API responses.
• Ruff quality gate and contributor templates for public maintenance.
• Python wheel build validation and MCP directory metadata for promotion readiness.
• No token persistence and no hardcoded credentials.

Tools

All mutating tools expose dry_run=True. Previews contain method and path, plus json when the request has a body; the HTTPS workflow returns two previews in steps. The flag suppresses mutating requests, though some previews read current state. Update tools send only the fields in NPM's PUT schema (fixes #19); this is covered by mocked tests and not yet checked against a live NPM instance.

Shortened. The full README is on GitHub.