Skip to content
Back to search

nginxpm-mcp

Nginx Proxy Manager MCP server — manage proxy hosts, certificates, and redirection hosts via MCP protocol

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/coe-artificial--nginxpm-mcp/badge.svg)](/listings/coe-artificial--nginxpm-mcp)

HTML

<a href="/listings/coe-artificial--nginxpm-mcp"><img src="/api/listings/coe-artificial--nginxpm-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# Clone & build
git clone https://github.com/coe-artificial/nginxpm-mcp.git
cd nginxpm-mcp
npm install
npm run build

# Install globally (optional)
npm install -g .

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 266 lines
  1. # Nginx Proxy Manager — MCP Server
  2. [![MIT License](https://img.shields.io/badge/license-MIT-green.svg?style=flat-square)](LICENSE)
  3. [![TypeScript](https://img.shields.io/badge/TypeScript-5.8-%23007ACC?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)
  4. [![Node.js](https://img.shields.io/badge/Node.js-22+-%23339933?style=flat-square&logo=node.js)](https://nodejs.org/)
  5. [![MCP SDK](https://img.shields.io/badge/MCP-%40modelcontextprotocol%2Fsdk%401.12.1-brightgreen?style=flat-square)](https://modelcontextprotocol.io/)
  6. [![Tools](https://img.shields.io/badge/tools-19-blue?style=flat-square)](#available-tools)
  7. > **Manage your Nginx Proxy Manager fleet from any MCP-host AI chat.** Create proxy hosts, rotate certificates, flip redirections — without ever opening the admin dashboard.
  8. ---
  9. ## Architecture
  10. ```
  11. ┌──────────────────────┐ ┌─────────────────────────┐ ┌───────────────────┐
  12. │ MCP Host (AI) │ │ nginxpm-mcp server │ │ Nginx Proxy Mgr │
  13. │ │ stdio │ │ HTTP │ │
  14. │ "Create a proxy │◄───────►│ McpServer │◄───────►│ /api/hosts │
  15. │ for api.example.com"│ │ ┌───────────────────┐ │ │ /api/certificates│
  16. │ │ │ │ list-proxy-hosts │ │ │ /api/tokens │
  17. │ "Renew cert #3" │ │ │ create-proxy-host │ │ │ │
  18. │ │ │ │ renew-certificate │ │ └───────────────────┘
  19. │ │ │ │ … 19 tools total │ │
  20. │ │ │ │ ↓ │ │
  21. │ │ │ │ [NpmClient×N] │ │
  22. │ │ │ └───────────────────┘ │
  23. └──────────────────────┘ └─────────────────────────┘
  24. ```
  25. Each config entry spawns an isolated `NpmClient` with its own JWT token cache and retry logic.
  26. ---
  27. ## Related
  28. - [Nginx Proxy Manager](https://github.com/NginxProxyManager/nginx-proxy-manager) — the upstream project
  29. - [Model Context Protocol](https://modelcontextprotocol.io/) — the MCP specification
  30. ---
  31. ## Features
  32. - **19 tools** covering full CRUD + enable/disable for proxy hosts, redirection hosts, and certificates
  33. - **Multi-instance** — manage several NPM deployments from one server instance
  34. - **Auto-reauth on 401/403** — transparent re-login without dropping requests
  35. - **Self-signed TLS** — works with dev instances using self-signed certificates
  36. - **Zero external deps** beyond the MCP SDK, undici, and zod
  37. ---
  38. ## Installation
  39. ```bash
  40. # Clone & build
  41. git clone https://github.com/coe-artificial/nginxpm-mcp.git
  42. cd nginxpm-mcp
  43. npm install
  44. npm run build
  45. # Install globally (optional)
  46. npm install -g .
  47. ```
  48. ---
  49. ## Configuration
  50. Create `npm-config.json` with one or more NPM instances:
  51. ```json
  52. {
  53. "dgx": {
  54. "address": "http://10.0.0.10:81",
  55. "username": "admin@example.com",
  56. "password": "your-password"
  57. },
  58. "production": {
  59. "address": "https://npm.example.com",
  60. "username": "admin@example.com",
  61. "password": "your-password"
  62. }
  63. }
  64. ```
  65. > **Tip:** This file is gitignored by default — never commit real credentials.
  66. Run the server:
  67. ```bash
  68. # Linux / macOS
  69. NPMCP_CONFIG=./npm-config.json nginxpm-mcp
  70. # Windows (PowerShell)
  71. $env:NPMCP_CONFIG = (Resolve-Path .\npm-config.json).Path
  72. nginxpm-mcp
  73. # Windows (CMD)
  74. set NPMCP_CONFIG=%cd%\npm-config.json
  75. nginxpm-mcp
  76. ```
  77. ---
  78. ## Usage with MCP Hosts
  79. ### Claude Desktop integration
  80. Add this to `claude_desktop_config.json`:
  81. ```json
  82. {
  83. "mcpServers": {
  84. "nginxpm": {
  85. "command": "nginxpm-mcp",
  86. "env": {
  87. "NPMCP_CONFIG": "C:\\Users\\you\\npm-config.json"
  88. }
  89. }
  90. }
  91. }
  92. ```
  93. ### Cursor / Windsurf integration
  94. ```jsonc
  95. // .cursor/mcp.json
  96. {
  97. "mcpServers": {
  98. "nginxpm": {
  99. "command": "npx",
  100. "args": ["nginxpm-mcp"],
  101. "env": {
  102. "NPMCP_CONFIG": "./npm-config.json"
  103. }
  104. }
  105. }
  106. }
  107. ```
  108. ---
  109. ## Usage Examples
  110. ### Example 1 — List all proxy hosts and summarize
  111. ```
  112. User: List all my proxy hosts and tell me which ones are disabled.
  113. AI → calls list-proxy-hosts → gets JSON array
  114. AI → parses response, reports:
  115. "You have 8 proxy hosts. 2 are disabled:
  116. - Host #3 (staging.example.com → 10.0.0.5:8080)
  117. - Host #7 (internal.example.com → 10.0.0.6:3000)"
  118. ```
  119. ### Example 2 — Create a reverse proxy with Let's Encrypt
  120. ```
  121. User: Set up a reverse proxy for api.internal.com pointing at 192.168.1.50:8443 with HTTPS.
  122. AI → calls create-proxy-host with:
  123. {
  124. "name": "api.internal.com",
  125. "domainNames": ["api.internal.com"],
  126. "forwardScheme": "https",
  127. "forwardHost": "192.168.1.50",
  128. "forwardPort": 8443,
  129. "certificate": null,
  130. "sslForce": true,
  131. "hstsEnabled": true
  132. }
  133. AI: "Proxy host created. Force HTTPS is enabled — all HTTP traffic will be redirected."
  134. ```
  135. ### Example 3 — Bulk enable all disabled redirections
  136. ```
  137. User: I'm decommissioning old services. Enable all disabled redirection hosts.
  138. AI → calls list-redirection-hosts → finds disabled ones
  139. AI → calls enable-redirection-host for each
  140. AI: "Enabled 3 redirection hosts. All are now live."
  141. ```
  142. ### Example 4 — Rotate a certificate
  143. ```
  144. User: Certificate #5 is about to expire. Renew it.
  145. AI → calls renew-certificate({ instance: "production", id: 5 })
  146. AI: "Certificate renewed successfully. Expiry is now 2027-02-15."
  147. ```
  148. ### Example 5 — Add a temporary redirect
  149. ```
  150. User: Point blog.example.com to https://newsite.example.com for now.
  151. AI → calls create-redirection-host with:
  152. {
  153. "name": "blog-redirect",
  154. "domains": ["blog.example.com"],
  155. "forwardScheme": "https",
  156. "forwardDomainName": "newsite.example.com",
  157. "forwardPort": 443,
  158. "preserveHost": true,
  159. "redirectCode": 302
  160. }
  161. AI: "Temporary redirect created (302). Blog visitors will be forwarded to the new site."
  162. ```
  163. ---
  164. ## Available Tools
  165. ### Proxy Hosts (7 tools)
  166. | Tool | Description |
  167. |------|-------------|
  168. | `list-proxy-hosts` | List all proxy hosts |
  169. | `get-proxy-host` | Get proxy host by ID |
  170. | `create-proxy-host` | Create a new proxy host |
  171. | `update-proxy-host` | Update a proxy host |
  172. | `delete-proxy-host` | Delete a proxy host |
  173. | `enable-proxy-host` | Enable a proxy host vhost |
  174. | `disable-proxy-host` | Disable a proxy host vhost |
  175. ### Certificates (6 tools)
  176. | Tool | Description |
  177. |------|-------------|
  178. | `list-certificates` | List all certificates |
  179. | `get-certificate` | Get certificate by ID |
  180. | `create-certificate` | Create a Let's Encrypt or manual certificate |
  181. | `renew-certificate` | Renew a certificate |
  182. | `delete-certificate` | Delete a certificate |
  183. ### Redirection Hosts (6 tools)
  184. | Tool | Description |
  185. |------|-------------|
  186. | `list-redirection-hosts` | List all redirection hosts |
  187. | `get-redirection-host` | Get redirection host by ID |
  188. | `create-redirection-host` | Create a new redirection host |
  189. | `update-redirection-host` | Update a redirection host |
  190. | `delete-redirection-host` | Delete a redirection host |
  191. | `enable-redirection-host` | Enable a redirection host vhost |
  192. | `disable-redirection-host` | Disable a redirection host vhost |
  193. ---
  194. ## How It Works
  195. 1. **Auth** — JWT Bearer tokens via `POST /api/tokens`, cached with proactive 60-second refresh
  196. 2. **Retry** — 401/403 triggers re-auth + retry; 5xx adds 200ms delay + retry
  197. 3. **Self-signed TLS** — `undici` agent with `rejectUnauthorized: false` for dev environments
  198. 4. **Multi-instance** — each config entry creates a separate `NpmClient` with its own token cache
  199. ---
  200. ## License
  201. MIT © [coe-artificial](https://github.com/coe-artificial)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.