nginx-proxy-manager-mcp

Nginx Proxy Manager MCP

Nginx Proxy Manager 用の MCP サーバーです。Claude などの MCP クライアントが、NPM 管理画面を操作する代わりに、型付きツールを使ってリバースプロキシホスト、Let's Encrypt 証明書、アクセスリストを管理できます。

"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) を呼び出し、リクエストのプレビューを2件出力します。実際の NPM インスタンスや認証情報は使用しません。再度記録するには、開発用の依存関係と VHS をインストールし、リポジトリのルートから vhs docs/demo.tape を実行してください。 docs/demo.py では、テストと同じ respx によるモック方法を使用します。

このプロジェクトの目的

リバースプロキシの変更は、ホームラボで繰り返し発生する作業です。ホストを作成し、コンテナを指定して、証明書を割り当て、必要に応じてアクセスリストで制限します。これは、範囲を絞った型付きツールとローカルの管理境界があれば、AI アシスタントが得意とする運用タスクです。

このサーバーは、次のいずれかの方法で実行できます。

• 既存の NPM コンテナの隣で SSE Docker サイドカーとして実行する
• ローカルクライアント向けの stdio MCP サーバーとして実行する

機能

• 一般的な NPM 操作に対応する32個の MCP ツール。
• すべての変更系ツールで dry_run を使い、適用前に NPM リクエストをプレビューできます。
• create_proxy_host_with_letsencrypt は証明書をリクエストした後、HTTPS を強制するプロキシホストを作成します。
• NPM API に対する JWT 認証に対応し、トークンをメモリ内にキャッシュして、401 時には自動で再認証します。
• MCP ポートをデフォルトで localhost にバインドする Docker サイドカーのデプロイ。
• モックした 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 は、プロキシホスト、リダイレクトホスト、ストリームをステータスで絞り込みます。4 つすべてで compact=True を指定すると、概要フィールドのみが返されます。フィルターは組み合わせて使用でき、引数なしで呼び出すと、変更されていない NPM の全リストが返されます。たとえば、list_proxy_hosts(domain="example", enabled=True, compact=True) は、「example」に一致する有効なホストを簡潔な出力で一覧表示します。

すべての変更ツールで dry_run=True を指定できます。プレビューには method と path が含まれ、リクエストにボディがある場合は json も含まれます。HTTPS ワークフローでは、steps に 2 つのプレビューが返されます。このフラグにより変更リクエストは抑止されますが、プレビューのために現在の状態を読み取る場合があります。更新ツールは NPM の PUT スキーマに含まれるフィールドのみを送信します（#19 を修正）。これはモックテストで検証済みですが、実際の NPM インスタンスではまだ確認されていません。

他の NPM MCP サーバーとの比較

以下の競合に関する情報は、2026-10-13 に gh api repos/<owner>/nginx-proxy-manager-mcp/readme で取得した、リンク先の README のみに基づいています。「記載なし」は、README で機能が確認できないことを意味し、その機能がないことを示すものではありません。認証ガードとは、NPM API のログインとは別の、受信する MCP クライアントの認証を指します。

リポジトリ	記載されているツール数	ドライランのサポート	トランスポート	認証ガード
euisuh（このサーバー）	32	すべての変更ツールで dry_run に対応	stdio、SSE	任意の SSE ベアラートークン（MCP_BEARER_TOKEN）。/healthz は対象外
b3nw	名前付きツール 14 個（カタログの行 13 個に list_instances を追加）	記載なし	stdio、HTTP	HTTP ベアラートークン（NPM_MCP_AUTH_TOKEN）
omichelbraga	66	confirm: true を指定しない DELETE では、影響を受けるリソースをプレビュー。一般的な dry_run は記載なし	stdio、Streamable HTTP	任意のベアラートークン（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 サイドカーを 127.0.0.1:8000:8000 で公開しています。これらは tools/、server.py、docker-compose.yml で確認できます。他のサーバーに同等の機能がないことを示すものではありません。

クイックスタート：Docker サイドカー

同梱の docker-compose.yml を使うと、Nginx Proxy Manager とこの MCP サイドカーがソースから起動します。すでに 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 クライアントからサーバープロセスを直接起動する場合は、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 リクエストに必要となる任意のベアラートークン

読み取り専用ツールのみを公開するには、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) 関数と登録行を1つ追加します。

開発

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 に公開します。

• v0.2.0 などのタグには ghcr.io/euisuh/nginx-proxy-manager-mcp:<version>
• semver タグには ghcr.io/euisuh/nginx-proxy-manager-mcp:<major>.<minor>
• 最新のタグ付きリリースには 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 インスタンスは 1 つです。マルチテナントやマルチホストルーティングには対応していません。
• オプションの SSE ベアラートークン認証で HTTP エンドポイントを保護できますが、クライアントの認証後にツールごとの認可を行う仕組みはありません。
• /healthz が報告するのはプロセスの稼働状況のみで、NPM への接続状況は確認しません。
• NPM v2 API を対象に実装されています。古い NPM ビルドやフォーク版では異なる場合があります。

コントリビューション

Issue とプルリクエストを歓迎します。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. respx でモックした NPM のレスポンスを使用し、各ツールを網羅する tests/test_<resource>.py を追加します。
4. ruff check . と pytest -q を実行します。

コミットには Conventional Commits を使用します。

作者

Euisuh Jeong が Claude Code からホームラボのリバースプロキシを管理するために開発し、メンテナンスしています。

ライセンス

MIT — LICENSE を参照してください。