Metadata-Version: 2.4
Name: nginx-proxy-manager-mcp-full
Version: 0.1.1
Summary: MCP server for Nginx Proxy Manager — 43 tools for proxy hosts, redirections, streams, dead hosts, certificates, access lists, and users
Project-URL: Repository, https://codeberg.org/BaeckBlog/nginx-proxy-manager-mcp
Project-URL: Issues, https://codeberg.org/BaeckBlog/nginx-proxy-manager-mcp/issues
License-Expression: MIT
License-File: LICENSE
Keywords: mcp,nginx-proxy-manager,npm,reverse-proxy
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Networking
Requires-Python: >=3.12
Requires-Dist: mcp>=1.27.0
Description-Content-Type: text/markdown

# nginx-proxy-manager-mcp

<!-- mcp-name: at.baeck/nginx-proxy-manager -->

MCP server for [Nginx Proxy Manager](https://nginxproxymanager.com/). 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:

```bash
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:

```bash
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

```bash
uv run python3 -m unittest discover tests -v
```

Tests use mocked HTTP — no live NPM instance required.

## License

MIT
