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+
mcppackage (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=your-email@example.com \
-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=your-email@example.com \
-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
1 maintainer
Metadata
1 maintainer
Release files for nginx-proxy-manager-mcp-full 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| nginx_proxy_manager_mcp_full-0.1.1.tar.gz | 12.5 kB | Without provenance | Details for nginx_proxy_manager_mcp_full-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| nginx_proxy_manager_mcp_full-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for nginx_proxy_manager_mcp_full-0.1.1-py3-none-any.whl |
Total release size: 32.2 kB
Release files / nginx_proxy_manager_mcp_full-0.1.1.tar.gz
| Download URL | nginx_proxy_manager_mcp_full-0.1.1.tar.gz |
|---|---|
| Size | 12.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
087bd7b580ae970c348ba939f96d69e1d782e276398af1b87988ae5f77401ea4
|
|
BLAKE2b-256 checksum How to use checksums |
c2bbdb0d160a7417f2b6e57bc51e6dba0c0595840753bddf6e1b7290080ea895
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / nginx_proxy_manager_mcp_full-0.1.1-py3-none-any.whl
| Download URL | nginx_proxy_manager_mcp_full-0.1.1-py3-none-any.whl |
|---|---|
| Size | 19.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
12d3d8d6a6f0a6b32084a6b5c86156e2036cbf30cde18fac4576db5f7466d60a
|
|
BLAKE2b-256 checksum How to use checksums |
0a7f4ee1ad848c6295c5b39394b4f2c331682b8ef6a1e5aaf3160606cb5bdec3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for nginx-proxy-manager-mcp-full 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
