Nginx Proxy Manager MCP

Nginx Proxy Manager MCP

An MCP server for Nginx Proxy Manager. It lets Claude and other MCP clients manage proxy hosts, redirection hosts, TCP/UDP streams, 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 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

• 34 MCP tools for common NPM operations (table below).
• 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.
• Let's Encrypt over HTTP-01 or DNS-01 (wildcards), with the request shape picked from the NPM version reported by GET /api/.
• NPM_READ_ONLY=true registers only the 12 list_/get_/find_ tools.
• 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, including end-to-end calls through the MCP protocol layer; CI runs it on Python 3.10–3.13.
• 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

The table is generated by docs/tools_table.py from the registered tools; tests/test_readme.py fails if it drifts. Read-only tools are the ones NPM_READ_ONLY keeps.

List tools support optional server-side filtering after fetching from NPM: domain matches a case-insensitive substring in any domain name for proxy hosts, redirection hosts, and certificates; enabled filters proxy hosts, redirection hosts, and streams by status. All four accept compact=True to return only summary fields. Filters combine, and calls without arguments return the full, unchanged NPM list. For example, list_proxy_hosts(domain="example", enabled=True, compact=True) lists enabled hosts matching "example" with compact output.

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.

This server's implementations expose dry_run on every mutating tool, provide the one-shot create_proxy_host_with_letsencrypt workflow, and publish the Docker sidecar at 127.0.0.1:8000:8000. These are verified in tools/, server.py, and docker-compose.yml. They do not establish that other servers lack equivalent capabilities.

Quick start: Docker sidecar

The bundled docker-compose.yml starts both Nginx Proxy Manager and this MCP sidecar from source. If you already run NPM, copy only the nginx-proxy-manager-mcp service into your existing compose file.

git clone https://github.com/euisuh/nginx-proxy-manager-mcp.git

cd nginx-proxy-manager-mcp cp .env.example .env

edit .env — NPM_EMAIL / NPM_PASSWORD of an existing NPM user (a dedicated non-admin user works; see Security)

docker compose up -d

NPM_URL defaults to http://app:81, the NPM admin API on the internal Docker network. Leave it as-is when both services share a compose stack; point it at your NPM host otherwise.

To use the published GHCR image instead of building locally:

services:

nginx-proxy-manager-mcp: image: ghcr.io/euisuh/nginx-proxy-manager-mcp:latest restart: unless-stopped environment: NPM_URL: http://app:81 NPM_EMAIL: ${NPM_EMAIL} N