nginx-proxy-manager-mcp-full 0.1.0

MCP server for Nginx Proxy Manager — 43 tools for proxy hosts, redirections, streams, dead hosts, certificates, access lists, and users

nginx-proxy-manager-mcp

MCP server for Nginx Proxy Manager. Exposes NPM's REST API as MCP tools for use with Claude Code and other MCP clients.

Prerequisites

• Python 3.12+
• mcp package (pip install mcp)
• A running Nginx Proxy Manager instance with API access

Configuration

All configuration is via environment variables. See .env.schema for the full list.

Variable	Required	Default	Description
NPM_BASE_URL	yes	—	NPM API base URL (e.g. http://192.168.1.100:81)
NPM_IDENTITY	yes	—	Login email for NPM API
NPM_SECRET	yes	—	Password for NPM API
NPM_TOKEN_REFRESH_MARGIN	no	300	Seconds before token expiry to trigger re-auth

Installation

Add to Claude Code with:

claude mcp add nginx-proxy-manager \
  -e NPM_BASE_URL=http://your-npm-host:81 \
  -e NPM_IDENTITY=[e-mail] \
  -e NPM_SECRET=your-password \
  -- python3 /path/to/nginx-proxy-manager-mcp/server.py

For 1Password users, wrap the command with op run to resolve secrets:

op run -- claude mcp add nginx-proxy-manager \
  -e NPM_BASE_URL=http://your-npm-host:81 \
  -e NPM_IDENTITY=[e-mail] \
  -e NPM_SECRET=op://Vault/Item/credential \
  -- python3 /path/to/nginx-proxy-manager-mcp/server.py

Project Structure

server.py          — entry point, FastMCP instance, main()
client.py          — HTTP client, auth, token management, _request()
helpers.py         — pure helper functions, validation, payload builders
tools/
  hosts.py         — proxy host tools (10)
  redirects.py     — redirection host tools (5)
  streams.py       — stream/TCP/UDP tools (5)
  dead.py          — dead host / 404 tools (5)
  certs.py         — certificate tools (6)
  acl.py           — access list tools (5)
  users.py         — user management tools (5)
tests/             — per-module test files

Tools

Proxy Hosts

Tool	Description
npm_list_hosts	List all proxy hosts with domain, backend, SSL, and health status
npm_get_host	Get full details for a proxy host by ID or domain search
npm_get_host_config	Get the generated nginx configuration for a proxy host
npm_create_host	Create a new proxy host
npm_update_host	Update proxy host settings (forward target, SSL, HSTS, websocket, etc.)
npm_delete_host	Delete a proxy host (requires explicit confirmation)
npm_enable_host	Enable a proxy host
npm_disable_host	Disable a proxy host
npm_find_hosts_by_cert	Find all proxy hosts using a specific certificate
npm_find_offline_hosts	Find all proxy hosts that are currently offline

Redirection Hosts

Tool	Description
npm_list_redirections	List all redirection hosts
npm_get_redirection	Get full details for a redirection host by ID
npm_create_redirection	Create a new redirection host (301/302/307/308)
npm_update_redirection	Update a redirection host's settings
npm_delete_redirection	Delete a redirection host (requires explicit confirmation)

Stream Hosts (TCP/UDP)

Tool	Description
npm_list_streams	List all TCP/UDP stream forwarding rules
npm_get_stream	Get full details for a stream by ID
npm_create_stream	Create a new stream forwarding rule
npm_update_stream	Update a stream's settings
npm_delete_stream	Delete a stream (requires explicit confirmation)

Dead Hosts (404)

Tool	Description
npm_list_dead_hosts	List all dead hosts
npm_get_dead_host	Get full details for a dead host by ID
npm_create_dead_host	Create a new dead host (custom 404 page)
npm_update_dead_host	Update a dead host's settings
npm_delete_dead_host	Delete a dead host (requires explicit confirmation)

Access Lists

Tool	Description
npm_list_access_lists	List all access lists with auth user and client rule counts
npm_get_access_list	Get full details including auth users and IP rules
npm_create_access_list	Create a new access list with auth users and/or IP rules
npm_update_access_list	Update an access list's settings
npm_delete_access_list	Delete an access list (requires explicit confirmation)

Certificates

Tool	Description
npm_list_certs	List SSL certificates with expiry dates
npm_request_cert	Provision a Let's Encrypt certificate (HTTP or DNS challenge)
npm_renew_cert	Force-renew a certificate
npm_delete_cert	Delete and revoke a certificate (requires explicit confirmation)
npm_test_http_challenge	Test if domains are reachable for HTTP challenge
npm_list_dns_providers	List available DNS providers for DNS challenge

Users

Tool	Description
npm_list_users	List all NPM users
npm_get_user	Get full details for a user by ID
npm_create_user	Create a new NPM user
npm_update_user	Update a user's settings (no password changes)
npm_delete_user	Delete a user (requires explicit confirmation)

Testing

uv run python3 -m unittest discover tests -v

Tests use mocked HTTP — no live NPM instance required.

License

MIT