nginxpm-mcp
# Nginx Proxy Manager — MCP Server
[](LICENSE)
[](https://www.typescriptlang.org/)
[](https://nodejs.org/)
[](https://modelcontextprotocol.io/)
[](#available-tools)
> **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.
---
## Architecture
```
┌──────────────────────┐ ┌─────────────────────────┐ ┌───────────────────┐
│ MCP Host (AI) │ │ nginxpm-mcp server │ │ Nginx Proxy Mgr │
│ │ stdio │ │ HTTP │ │
│ "Create a proxy │◄───────►│ McpServer │◄───────►│ /api/hosts │
│ for api.example.com"│ │ ┌───────────────────┐ │ │ /api/certificates│
│ │ │ │ list-proxy-hosts │ │ │ /api/tokens │
│ "Renew cert #3" │ │ │ create-proxy-host │ │ │ │
│ │ │ │ renew-certificate │ │ └───────────────────┘
│ │ │ │ … 19 tools total │ │
│ │ │ │ ↓ │ │
│ │ │ │ [NpmClient×N] │ │
│ │ │ └───────────────────┘ │
└──────────────────────┘ └─────────────────────────┘
```
Each config entry spawns an isolated `NpmClient` with its own JWT token cache and retry logic.
---
## Related
- [Nginx Proxy Manager](https://github.com/NginxProxyManager/nginx-proxy-manager) — the upstream project
- [Model Context Protocol](https://modelcontextprotocol.io/) — the MCP specification
---
## Features
- **19 tools** covering full CRUD + enable/disable for proxy hosts, redirection hosts, and certificates
- **Multi-instance** — manage several NPM deployments from one server instance
- **Auto-reauth on 401/403** — transparent re-login without dropping requests
- **Self-signed TLS** — works with dev instances using self-signed certificates
- **Zero external deps** beyond the MCP SDK, undici, and zod
---
## Installation
```bash
# 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 .
```
---
## Configuration
Create `npm-config.json` with one or more NPM instances:
```json
{
"dgx": {
"address": "http://10.0.0.10:81",
"username": "admin@example.com",
"password": "your-password"
},
"production": {
"address": "https://npm.example.com",
"username": "admin@example.com",
"password": "your-password"
}
}
```
> **Tip:** This file is gitignored by default — never commit real credentials.
Run the server:
```bash
# Linux / macOS
NPMCP_CONFIG=./npm-config.json nginxpm-mcp
# Windows (PowerShell)
$env:NPMCP_CONFIG = (Resolve-Path .\npm-config.json).Path
nginxpm-mcp
# Windows (CMD)
set NPMCP_CONFIG=%cd%\npm-config.json
nginxpm-mcp
```
---
## Usage with MCP Hosts
### Claude Desktop integration
Add this to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"nginxpm": {
"command": "nginxpm-mcp",
"env": {
"NPMCP_CONFIG": "C:\\Users\\you\\npm-config.json"
}
}
}
}
```
### Cursor / Windsurf integration
```jsonc
// .cursor/mcp.json
{
"mcpServers": {
"nginxpm": {
"command": "npx",
"args": ["nginxpm-mcp"],
"env": {
"NPMCP_CONFIG": "./npm-config.json"
}
}
}
}
```
---
## Usage Examples
### Example 1 — List all proxy hosts and summarize
```
User: List all my proxy hosts and tell me which ones are disabled.
AI → calls list-proxy-hosts → gets JSON array
AI → parses response, reports:
"You have 8 proxy hosts. 2 are disabled:
- Host #3 (staging.example.com → 10.0.0.5:8080)
- Host #7 (internal.example.com → 10.0.0.6:3000)"
```
### Example 2 — Create a reverse proxy with Let's Encrypt
```
User: Set up a reverse proxy for api.internal.com pointing at 192.168.1.50:8443 with HTTPS.
AI → calls create-proxy-host with:
{
"name": "api.internal.com",
"domainNames": ["api.internal.com"],
"forwardScheme": "https",
"forwardHost": "192.168.1.50",
"forwardPort": 8443,
"certificate": null,
"sslForce": true,
"hstsEnabled": true
}
AI: "Proxy host created. Force HTTPS is enabled — all HTTP traffic will be redirected."
```
### Example 3 — Bulk enable all disabled redirections
```
User: I'm decommissioning old services. Enable all disabled redirection hosts.
AI → calls list-redirection-hosts → finds disabled ones
AI → calls enable-redirection-host for each
AI: "Enabled 3 redirection hosts. All are now live."
```
### Example 4 — Rotate a certificate
```
User: Certificate #5 is about to expire. Renew it.
AI → calls renew-certificate({ instance: "production", id: 5 })
AI: "Certificate renewed successfully. Expiry is now 2027-02-15."
```
### Example 5 — Add a temporary redirect
```
User: Point blog.example.com to https://newsite.example.com for now.
AI → calls create-redirection-host with:
{
"name": "blog-redirect",
"domains": ["blog.example.com"],
"forwardScheme": "https",
"forwardDomainName": "newsite.example.com",
"forwardPort": 443,
"preserveHost": true,
"redirectCode": 302
}
AI: "Temporary redirect created (302). Blog visitors will be forwarded to the new site."
```
---
## Available Tools
### Proxy Hosts (7 tools)
| Tool | Description |
|------|-------------|
| `list-proxy-hosts` | List all proxy hosts |
| `get-proxy-host` | Get proxy host by ID |
| `create-proxy-host` | Create a new proxy host |
| `update-proxy-host` | Update a proxy host |
| `delete-proxy-host` | Delete a proxy host |
| `enable-proxy-host` | Enable a proxy host vhost |
| `disable-proxy-host` | Disable a proxy host vhost |
### Certificates (6 tools)
| Tool | Description |
|------|-------------|
| `list-certificates` | List all certificates |
| `get-certificate` | Get certificate by ID |
| `create-certificate` | Create a Let's Encrypt or manual certificate |
| `renew-certificate` | Renew a certificate |
| `delete-certificate` | Delete a certificate |
### Redirection Hosts (6 tools)
| Tool | Description |
|------|-------------|
| `list-redirection-hosts` | List all redirection hosts |
| `get-redirection-host` | Get redirection host by ID |
| `create-redirection-host` | Create a new redirection host |
| `update-redirection-host` | Update a redirection host |
| `delete-redirection-host` | Delete a redirection host |
| `enable-redirection-host` | Enable a redirection host vhost |
| `disable-redirection-host` | Disable a redirection host vhost |
---
## How It Works
1. **Auth** — JWT Bearer tokens via `POST /api/tokens`, cached with proactive 60-second refresh
2. **Retry** — 401/403 triggers re-auth + retry; 5xx adds 200ms delay + retry
3. **Self-signed TLS** — `undici` agent with `rejectUnauthorized: false` for dev environments
4. **Multi-instance** — each config entry creates a separate `NpmClient` with its own token cache
---
## License
MIT © [coe-artificial](https://github.com/coe-artificial)
TDQS
Scored across 19 tools
Each tool pairs a distinct verb with one of three clearly named resources (proxy-host, certificate, redirection-host), so selection is mostly unambiguous. The only soft overlap is enable/disable versus update, since an agent could plausibly toggle a host's state through update-proxy-host instead of the dedicated enable/disable tools.
Every tool follows the same kebab-case verb_noun convention (list-proxy-hosts, get-certificate, create-redirection-host, disable-proxy-host). Resource names are used identically across all verbs, making the naming fully predictable.
19 tools is on the heavier side, but the count is justified: roughly six to seven lifecycle operations each across three resource types (proxy hosts, certificates, redirection hosts). No tool appears redundant or filler.
Proxy hosts and redirection hosts have complete CRUD plus enable/disable, but certificates lack an update operation and the description explicitly notes the manual-provider two-step workflow is not exposed. Broader NPM features (stream/TCP hosts, access lists, dead/404 hosts) are absent, leaving notable gaps for a full Nginx Proxy Manager surface.