nginx-proxy-manager-mcp

Nginx Proxy Manager MCP

一个用于 Nginx Proxy Manager 的 MCP 服务。它让 Claude 和其他 MCP 客户端通过类型化工具管理反向代理主机、Let's Encrypt 证书和访问列表，无需在 NPM 管理界面中逐项点击。

"Point blog.example.com at the container on port 3000 with HTTPS"
      │
      ▼
Claude / MCP client ──► Nginx Proxy Manager MCP ──HTTP + JWT──► NPM API

该演示通过模拟的 NPM API 调用 create_proxy_host_with_letsencrypt(dry_run=True)，并打印两个请求的预览。不会使用真实的 NPM 实例或凭据。若要重新录制，请安装开发依赖和 VHS，然后在代码库根目录运行 vhs docs/demo.tape；docs/demo.py 使用了与测试相同的 respx 模拟方式。

为什么要开发它

反向代理变更是家庭实验室中重复性很高的工作：创建主机，将其指向容器，附加证书，有时还要限制其访问某个访问列表。如果 AI 助手拥有范围明确的类型化工具和本地管理边界，就能很好地处理这类运维任务。

此服务可以：

• 作为 SSE Docker sidecar，与现有 NPM 容器并行运行，或
• 作为供本地客户端使用的 stdio MCP 服务运行。

功能

• 提供 32 个用于常见 NPM 操作的 MCP 工具。
• 所有会修改数据的工具都支持 dry_run，可在应用变更前预览 NPM 请求；
• 一次性调用 create_proxy_host_with_letsencrypt 来申请证书，然后创建强制使用 HTTPS 的代理主机。
• 使用 JWT 向 NPM API 进行身份验证，在内存中缓存令牌，并在收到 401 时自动重新认证。
• Docker sidecar 部署默认将 MCP 端口绑定到 localhost。
• 使用模拟 NPM API 响应的离线 pytest 测试套件。
• 提供 Ruff 质量门禁和供公开维护使用的贡献者模板。
• 提供 Python wheel 构建验证和 MCP 目录元数据，为推广做好准备。
• 不持久化令牌，也不硬编码凭据。

工具

类别	工具
工作流	create_proxy_host_with_letsencrypt
诊断	find_host_by_domain、list_expiring_certificates
代理主机	list_proxy_hosts、get_proxy_host、create_proxy_host、update_proxy_host、delete_proxy_host、enable_proxy_host、disable_proxy_host
重定向主机	list_redirection_hosts、get_redirection_host、create_redirection_host、update_redirection_host、delete_redirection_host、enable_redirection_host、disable_redirection_host
流	list_streams、get_stream、create_stream、update_stream、delete_stream、enable_stream、disable_stream
SSL 证书	list_certificates、create_letsencrypt_cert、renew_certificate
访问列表	list_access_lists、get_access_list、create_access_list、update_access_list、delete_access_list

列表工具支持在从 NPM 获取数据后进行可选的服务端筛选：domain 会在代理主机、重定向主机和证书的任意域名中匹配不区分大小写的子字符串；enabled 会按状态筛选代理主机、重定向主机和流。以上四种工具都接受 compact=True，仅返回摘要字段。筛选条件会组合使用；不带参数调用时，会返回完整且未经更改的 NPM 列表。例如，list_proxy_hosts(domain="example", enabled=True, compact=True) 会以紧凑格式列出域名匹配“example”的已启用主机。

所有会修改数据的工具都支持 dry_run=True。预览包含 method 和 path；请求包含正文时还会包含 json；HTTPS 工作流会在 steps 中返回两个预览。该标志会阻止发送修改请求，但部分预览会读取当前状态。更新工具只会发送 NPM PUT 架构中包含的字段（修复 #19）；此行为已通过模拟测试覆盖，但尚未在运行中的 NPM 实例上验证。

与其他 NPM MCP 服务的比较

以下竞争产品信息仅来自其关联 README，这些 README 于 2026-10-13 通过 gh api repos/<owner>/nginx-proxy-manager-mcp/readme 获取。“未记录”表示 README 未证明具备该功能，并不代表缺少该功能。身份验证防护指传入 MCP 客户端身份验证，与 NPM API 登录不同。

仓库	记录的工具数量	演练支持	传输方式	身份验证防护
euisuh（本服务）	32	所有修改类工具均支持 dry_run	stdio、SSE	可选的 SSE bearer token（MCP_BEARER_TOKEN）；/healthz 不受限制
b3nw	14 个具名工具（目录中的 13 行加上 list_instances）	未记录	stdio、HTTP	HTTP bearer token（NPM_MCP_AUTH_TOKEN）
omichelbraga	66	DELETE 操作未设置 confirm: true 时会预览受影响的资源；未记录通用的 dry_run	stdio、Streamable HTTP	可选的 bearer token（NPM_MCP_BEARER_TOKEN）；未设置时不进行传入身份验证
drmogie	4 个具名工具（npm_status、npm_hosts、npm_audit_log、npm_call）	会显示将要发送的更改，并要求 confirm；未记录 dry_run	未记录	未记录

本服务的实现为每个修改类工具提供 dry_run，提供一次性 create_proxy_host_with_letsencrypt 工作流，并将 Docker sidecar 发布在 127.0.0.1:8000:8000。这些信息已在 tools/、server.py 和 docker-compose.yml 中验证。它们不能证明其他服务不具备同等功能。

快速开始：Docker sidecar

随附的 docker-compose.yml 会从源代码启动 Nginx Proxy Manager 和此 MCP sidecar。如果你已经在运行 NPM，只需将 nginx-proxy-manager-mcp 服务复制到现有的 compose 文件中。

git clone https://github.com/euisuh/nginx-proxy-manager-mcp.git
cd nginx-proxy-manager-mcp
cp .env.example .env
# edit .env — NPM_EMAIL / NPM_PASSWORD must be an existing NPM admin account
docker compose up -d

NPM_URL 默认为 http://app:81，即内部 Docker 网络上的 NPM 管理 API。如果两个服务位于同一个 compose 堆栈中，请保持默认值；否则，将其指向你的 NPM 主机。

要使用已发布的 GHCR 镜像，而不是在本地构建：

services:
  nginx-proxy-manager-mcp:
    image: ghcr.io/euisuh/nginx-proxy-manager-mcp:latest
    restart: unless-stopped
    environment:
      NPM_URL: http://app:81
      NPM_EMAIL: ${NPM_EMAIL}
      NPM_PASSWORD: ${NPM_PASSWORD}
      MCP_TRANSPORT: sse
      MCP_HOST: 0.0.0.0
      MCP_PORT: 8000
      MCP_BEARER_TOKEN: ${MCP_BEARER_TOKEN:-}
    ports:
      - "127.0.0.1:8000:8000"

使用 Claude Code 注册 SSE 服务：

claude mcp add npm http://localhost:8000/sse

或者手动将其添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "nginx-proxy-manager": {
      "url": "http://localhost:8000/sse"
    }
  }
}

更多示例请参阅 examples/：Claude Desktop、Claude Code、Cursor 和 Windsurf。

快速开始：uvx / pipx

如果不想使用 Docker，可以从 PyPI 运行（软件包 nginx-proxy-manager-mcp-server）：

NPM_URL=http://localhost:81 \
[email protected] \
NPM_PASSWORD=... \
MCP_TRANSPORT=stdio \
uvx nginx-proxy-manager-mcp-server

也可以从本地检出版本运行：

git clone https://github.com/euisuh/nginx-proxy-manager-mcp.git
cd nginx-proxy-manager-mcp

NPM_URL=http://localhost:81 \
[email protected] \
NPM_PASSWORD=... \
MCP_TRANSPORT=stdio \
uvx --from . nginx-proxy-manager-mcp

或者将其安装到隔离环境中：

pipx install nginx-proxy-manager-mcp-server

快速开始：stdio

如果你希望 MCP 客户端直接启动服务进程，而不是与 sidecar 通信，请使用 stdio。

python -m venv .venv
. .venv/bin/activate
pip install -e .
NPM_URL=http://localhost:81 \
[email protected] \
NPM_PASSWORD=... \
MCP_TRANSPORT=stdio \
nginx-proxy-manager-mcp

客户端配置示例：

{
  "mcpServers": {
    "nginx-proxy-manager": {
      "command": "/path/to/nginx-proxy-manager-mcp/.venv/bin/python",
      "args": ["-m", "nginx_proxy_manager_mcp.server"],
      "env": {
        "NPM_URL": "http://localhost:81",
        "NPM_EMAIL": "[email protected]",
        "NPM_PASSWORD": "...",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

配置

变量	必需	默认值	说明
NPM_URL	是	—	NPM 管理 API 的基础 URL（Docker 内部为 http://app:81）
NPM_EMAIL	是	—	NPM 管理员账户邮箱
NPM_PASSWORD	是	—	NPM 管理员账户密码
NPM_READ_ONLY	否	已禁用	1、true 或 yes（不区分大小写）时，仅注册 list_、get_ 和 find_ 工具；其他所有值都会禁用只读模式
MCP_TRANSPORT	否	sse	MCP 传输方式：sse 或 stdio
MCP_HOST	否	127.0.0.1	SSE 模式的绑定地址；Docker Compose 会在容器内设置为 0.0.0.0，同时仅向 localhost 发布
MCP_PORT	否	8000	SSE 模式的绑定端口
MCP_BEARER_TOKEN	否	—	SSE HTTP 请求所需的可选 bearer token

设置 NPM_READ_ONLY=true，即可仅提供只读工具。

如果缺少必需变量，服务会在启动时明确报错并退出，而不是等到首次 API 调用时才失败。

SSE 模式还会提供 GET /healthz，这是一个无需身份验证的存活状态端点，会返回简短的 JSON 响应。它不会联系 NPM，也不会验证凭据；仅将其用于容器和反向代理的健康检查。

架构

┌───────────────┐   MCP over SSE/stdio   ┌──────────────────────────┐
│ Claude/Cursor │ ─────────────────────► │ Nginx Proxy Manager MCP  │
│ / MCP client  │                        │ server.py + tools/       │
└───────────────┘                         └───────────┬──────────────┘
                                                       │ HTTP + Bearer JWT
                                                       ▼
                                           ┌──────────────────────────┐
                                           │ Nginx Proxy Manager API  │
                                           │ app:81 / localhost:81    │
                                           └──────────────────────────┘

• nginx_proxy_manager_mcp/server.py 会验证必需的环境变量、构建 FastMCP 应用、注册所有工具模块，并通过 SSE 或 stdio 提供服务。
• nginx_proxy_manager_mcp/npm_client.py 封装 httpx，首次使用时会用管理员邮箱和密码换取 JWT，在内存中缓存令牌，并在收到 401 时重新进行身份验证。
• nginx_proxy_manager_mcp/tools/ 为每种 NPM 资源保留一个模块。添加资源只需添加一个 register_*_tools(mcp, client) 函数和一行注册代码。

开发

python -m venv .venv
. .venv/bin/activate
pip install -e . -r requirements-dev.txt
pytest -q

测试使用 respx 模拟 NPM API，因此测试套件可离线运行，不会接触任何真实基础设施。CI 会在每次推送和拉取请求时运行相同的命令。

发布

带标签的发布版本（vX.Y.Z）会通过可信发布（.github/workflows/publish.yml）将 nginx-proxy-manager-mcp-server 软件包发布到 PyPI，并将多架构 Docker 镜像发布到 GitHub Container Registry：

• ghcr.io/euisuh/nginx-proxy-manager-mcp:<version>，适用于 v0.2.0 等标签
• ghcr.io/euisuh/nginx-proxy-manager-mcp:<major>.<minor>，适用于 semver 标签
• ghcr.io/euisuh/nginx-proxy-manager-mcp:latest，适用于最新的带标签发布版本

Docker 工作流也会构建拉取请求，但不会推送镜像，因此可以在发布前验证打包变更。

安全

任何能够访问此 MCP 服务的对象，都拥有对代理主机和证书的管理员级控制权限。

• 不要将 MCP 端点公开到公网。
• 除非另有可信网络边界，否则请将 Docker 端口绑定到 127.0.0.1。
• 独立运行的 SSE 默认绑定到 127.0.0.1；只有在可信网络边界之后，才设置 MCP_HOST=0.0.0.0。
• 对于任何可从本机以外访问的 SSE 部署，请设置 MCP_BEARER_TOKEN，并配置客户端发送 Authorization: Bearer YOUR_TOKEN。
• 使用环境变量或密钥管理器保存 NPM 凭据；不要提交 .env。
• NPM 管理员 JWT 仅驻留在进程内存中，不会写入磁盘。
• 容器以非 root 用户身份运行。

有关报告问题和部署指南，请参阅 SECURITY.md。

路线图

请参阅 ROADMAP.md。近期优先事项包括发布到 PyPI、提交至 MCP 目录、扩大 NPM 资源覆盖范围，以及集成测试。

目录元数据

• smithery.yaml 描述了适用于 Smithery 风格 MCP 目录的 stdio 启动配置。
• glama.json 声明了用于 Glama MCP 注册表验证的仓库维护者。

限制

• 仅支持代理主机、重定向主机、流、证书和访问列表。404 主机、用户、审计日志和设置尚未实现。
• 证书创建仅支持 Let's Encrypt HTTP-01，不支持 DNS-01 挑战，也暂不支持上传自定义证书。
• 每个服务进程仅支持一个 NPM 实例；不支持多租户或多主机路由。
• 可选的 SSE bearer 令牌身份验证可以保护 HTTP 端点，但客户端通过身份验证后，不会对单个工具进行授权。
• /healthz 仅报告进程是否存活，不报告 NPM 是否可访问。
• 本项目基于 NPM v2 API 编写；较旧版本或分支版本的 NPM 可能有所不同。

贡献

欢迎提交问题和拉取请求。请参阅 CONTRIBUTING.md。添加新的 NPM 资源需遵循固定步骤：

1. 创建 nginx_proxy_manager_mcp/tools/<resource>.py，并实现 register_<resource>_tools(mcp, client) 函数。
2. 在 nginx_proxy_manager_mcp/server.py 的 build_server() 中注册它。
3. 添加 tests/test_<resource>.py，使用 respx 模拟的 NPM 响应覆盖每个工具。
4. 运行 ruff check . 和 pytest -q。

提交信息遵循 Conventional Commits 规范。

作者

由 Euisuh Jeong 构建并维护，用于通过 Claude Code 管理家庭实验室反向代理。

许可证

MIT — 参见 LICENSE。