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.
The demo calls create_proxy_host_with_letsencrypt(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 create_proxy_host_with_letsencrypt 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
| Category | Tools |
|---|---|
| Workflows | create_proxy_host_with_letsencrypt |
| Proxy hosts | list_proxy_hosts, get_proxy_host, create_proxy_host, update_proxy_host, delete_proxy_host, enable_proxy_host, disable_proxy_host |
| Redirection hosts | list_redirection_hosts, get_redirection_host, create_redirection_host, update_redirection_host, delete_redirection_host, enable_redirection_host, disable_redirection_host |
| Streams | list_streams, get_stream, create_stream, update_stream, delete_stream, enable_stream, disable_stream |
| SSL certs | list_certificates, create_letsencrypt_cert, renew_certificate |
| Access lists | list_access_lists, get_access_list, create_access_list, update_access_list, delete_access_list |
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.
Compared to other NPM MCP servers
Competitor facts below come only from their linked READMEs fetched with gh api repos/ /nginx-proxy-manager-mcp/readme on 2026-10-13. “not documented” means the README does not establish the capability, not that it is absent. Auth guard means inbound MCP client authentication, distinct from NPM API login.
| Repository | Tool count documented | Dry-run support | Transport | Auth guard |
|---|---:|---|---|---|
| euisuh (this server) | 30 | dry_run on all mutating tools | stdio, SSE | Optional SSE bearer token (MCP_BEARER_TOKEN); /healthz exempt |
| b3nw | 14 named tools (13 catalog rows plus list_instances) | not documented | stdio, HTTP | HTTP bearer token (NPM_MCP_AUTH_TOKEN) |
| omichelbraga | 66 | DELETE without confirm: true previews affected resources; general dry_run not documented | stdio, Streamable HTTP | Optional bearer token (NPM_MCP_BEARER_TOKEN); unset means no inbound auth |