Skip to main content
Glama
nginx-certbot-mcp

nginx-certbot-mcp

nginx-certbot-mcp

CI

Let AI agents manage production web infrastructure without giving them root shell access.

nginx-certbot-mcp provisions Nginx reverse proxies, DNS records, and Let's Encrypt certificates through narrowly scoped, auditable MCP tools — never arbitrary shell commands. Privileged actions go through purpose-built wrappers and least-privilege sudo rules (see Why a wrapper script below).

Architecture

nginx-certbot-mcp architecture

Related MCP server: npm-mcp

Tools

All 26 are implemented and exercised against real infrastructure — see Testing.

Tool

Description

list_sites

List configured nginx server blocks with domain, upstream, and SSL status

get_site_config

Raw nginx config for one domain

check_cert_expiry

List certbot-managed certs and days until expiry

check_dns

Resolve a domain (CNAME, then A/AAAA) against public resolvers

check_upstream_health

TCP probe of an upstream host:port

get_nginx_status

Whether nginx is running, plus its version

diagnose_site

One-call health report for a domain: config, nginx, DNS, upstream, certificate, recent errors — with suggested next tools

tail_site_logs

Tail access/error logs, capped at 1000 lines

list_archived_sites

List configs archived by delete_site

list_site_backups

List the automatic pre-change backups of site configs

create_domain_record

Upsert a Route 53 CNAME

delete_domain_record

Delete a Route 53 CNAME — confirm:true

create_txt_record

Upsert a Route 53 TXT record, e.g. for ACME DNS-01

delete_txt_record

Delete a Route 53 TXT record — confirm:true

create_site

Create a websocket-capable nginx server block from the default template

update_site

Rewrite an existing site's proxy_pass upstream in place

delete_site

Disable, archive, and delete a server block — confirm:true

restore_site

Re-enable a site from its newest (or a chosen) archive — confirm:true

rollback_site

Undo a config change by restoring the newest (or a chosen) backup — confirm:true

prune_archives

Delete archives older than N days — confirm:true

reload_nginx

nginx -t, then reload only if it passes

issue_cert

Issue via HTTP-01 (certbot --nginx) — defaults to LE staging

issue_wildcard_cert

Issue domain + *.domain via DNS-01 (certbot --dns-route53) — defaults to LE staging

renew_cert

certbot renew — defaults to --dry-run

revoke_cert

Revoke with Let's Encrypt, leaving the files in place — confirm:true

delete_cert

Remove a cert's files from certbot's store — confirm:true

Setup

npm install
npm run build
npm run setup -- mcpuser

Run the server as a dedicated non-root user (e.g. mcpuser) — never as root. npm run setup -- <user> (scripts/setup.sh) grants that user exactly the privileges below, nothing more, and is idempotent: safe to re-run any time, including after changing the username or pulling an update that adds a new allowed command.

Required permissions

npm run setup -- <user> installs two things:

  1. /usr/local/bin/nginx-mcp-writesite — a narrow wrapper script that only accepts {write|enable|disable|remove|archive|restore|remove-archive|backup|restore-backup} <domain> or log {access|error} <lines>, and only ever touches paths under /etc/nginx/sites-available/, /etc/nginx/sites-enabled/, /etc/nginx/sites-archived/, /etc/nginx/sites-backups/, and the two fixed nginx log files. It re-validates the domain (and, for restore/remove-archive/restore-backup, the archive or backup filename) itself, independent of the Node-side validation.

  2. /etc/sudoers.d/nginx-mcp — grants <user> passwordless sudo on exactly nginx -t, systemctl reload nginx, systemctl is-active --quiet nginx, certbot, and the wrapper above. Nothing broader. It also keeps AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY/ AWS_DEFAULT_REGION through sudo (which strips the environment by default) so certbot --dns-route53 can see them for issue_wildcard_cert.

issue_wildcard_cert also needs the certbot-dns-route53 plugin — npm run install:deps installs it for you (see Testing).

Why a wrapper script instead of sudo on tee/ln/rm

An earlier version granted sudo on generic file tools (tee, ln, rm) so create_site could write into /etc/nginx/. That works, but it's a wider trust boundary than the task needs: those commands can touch any root-owned file on the box, not just nginx configs. If the MCP server process were ever compromised or triggered unexpectedly, the blast radius would be the whole filesystem.

The wrapper narrows that to one purpose-built binary that can only act on nginx site configs, one archive at a time, or tail one of two fixed log files — nothing else. The trade-off is one more artifact to deploy and keep in sync with the server, in exchange for sudo that can only ever do what this project needs.

Network requirements for certificate issuance

HTTP-01 and DNS-01 network requirements

issue_cert and issue_wildcard_cert prove domain ownership two different ways, with different requirements on where the box sits on your network:

  • issue_cert (HTTP-01) — Let's Encrypt makes an inbound HTTP request to the domain on port 80. If you're behind a home/office router doing NAT, that request lands on whichever one private IP your port-forwarding rule targets. The machine running nginx (and this MCP server) has to be that exact machine — not just any box on your network, and not the Docker sandbox (a different private IP on the Docker bridge network). Calling it from the wrong box fails every time, since the challenge request never arrives.

  • issue_wildcard_cert (DNS-01) — validates via a TXT record certbot-dns-route53 creates in Route 53. This is outbound-only (the box calls the AWS API; nothing calls back in), so it has no port-forwarding requirement and works identically from any network, including the Docker sandbox.

Either way, DNS still has to point at your public IP (create_domain_record handles that) — DNS and port-forwarding are two separate requirements, and issue_cert needs both.

Safety controls

Beyond the per-tool confirm gates and staging-by-default, the server has operator-level controls that an agent can't turn off from inside a conversation. Everything is configured through environment variables (see Environment variables).

Audit log

Every mutating tool call is appended to a JSONL file — timestamp, tool, arguments, MCP client, whether it was a dry run, outcome, and a one-line result — including calls that were refused. Credentials in arguments are redacted and long values truncated.

{"ts":"2026-09-19T10:02:11.402Z","tool":"delete_site","mutating":true,"client":"claude-code/2.1.0","args":{"domain":"old.example.com","confirm":true},"dry_run":false,"outcome":"ok","message":"Removed \"old.example.com\" (disabled, archived ...","duration_ms":212}

outcome is ok, failed (the tool ran and reported success:false, including an unconfirmed dry run), error (it threw), or denied.

  • Default path is ~/.nginx-certbot-mcp/audit.jsonl (mode 0600); override with AUDIT_LOG_PATH, or set AUDIT_LOG_PATH=off to disable.

  • The server refuses to start if the log isn't writable — you find out at startup, not after the first change.

  • Read-only calls are skipped by default; set AUDIT_LOG_READS=true to include them.

  • The file grows forever; point logrotate at it if that matters.

Read-only mode and tool allowlist

Hand an agent visibility without write access, or expose only the tools a workflow needs. Tools that are switched off are never registered, so the agent can't see or call them.

MCP_MODE=readonly                       # only tools annotated read-only
MCP_ENABLED_TOOLS="check_*,list_sites"  # only these (* is a wildcard)
  • MCP_MODE is readwrite (default) or readonly. Read-only mode drops every tool that changes state — DNS, nginx config, certificates, reloads.

  • MCP_ENABLED_TOOLS is a comma-separated list of tool names or * patterns. When both are set, a tool must pass both.

  • An invalid MCP_MODE, or an allowlist entry that matches no tool, is reported on stderr at startup (the former is fatal) rather than silently exposing the wrong set.

Domain allowlist

Confine the agent to the domains it's meant to manage, so a confused or manipulated agent can't edit, delete, or issue certificates for anything else on the box.

ALLOWED_DOMAINS="example.com,*.example.com"
  • example.com matches exactly that name; *.example.com matches any subdomain at any depth, not the apex — list both if you want both. A bare TLD (*.com) is rejected at startup.

  • Applies to every tool's domain argument, read-only tools included, and to Route 53 record names (_acme-challenge.a.example.com matches *.example.com).

  • issue_wildcard_cert for example.com also covers *.example.com, so both must be allowed.

  • Listings (list_sites, check_cert_expiry, list_archived_sites) only show in-scope domains, and prune_archives only touches in-scope archives.

  • renew_cert and tail_site_logs normally act on everything when domain is omitted; with an allowlist they require one.

  • Refused calls return a Denied by policy error and are written to the audit log with outcome denied.

This limits which domains the tools act on; it doesn't change what the sudo rules permit the server user to do — see Required permissions.

Config backups and rollback

create_site, update_site, restore_site and rollback_site snapshot a site's existing config before changing it, and each one restores that snapshot itself if the new config fails nginx -t — so a broken change never stays on disk. Backups also cover the case nginx -t can't catch: a config that is valid but wrong (the wrong upstream, say).

  • list_site_backups shows the snapshots, newest first; rollback_site restores the newest one by default (the config as it was before the last change) or a chosen backup_filename. It needs confirm:true.

  • Rolling back snapshots the current config first, so calling it again flips back — a rollback is never a one-way door.

  • The newest 10 backups per domain are kept in /etc/nginx/sites-backups/; older ones are deleted automatically.

  • If a snapshot can't be taken, the change is refused rather than made without a safety net. After upgrading, re-run npm run setup -- <user> so the installed helper knows the backup action.

  • Backups are separate from delete_site's archives: those are "this site was deleted", backups are "what it looked like before the last change".

  • reload_nginx still only reloads a config that passes nginx -t; when it refuses, its hint points at rollback_site.

Production issuance guard

Let's Encrypt's production rate limits punish retry loops, and a lockout can last a week. issue_cert and issue_wildcard_cert keep a local history of production (staging:false) attempts and refuse a request that would exceed a limit — before spending it:

Limit

Guard refuses when

Duplicate certificates

5 certs for the exact same set of names in 7 days

Failed validations

5 failed validations for a name in 1 hour

Certificates per registered domain

50 certs for one registered domain in 7 days

A refusal says which limit was hit and when to retry; a Heads-up note in rate_limit_note appears as a limit gets close. Staging requests are never counted or refused.

  • It counts only what was issued through this server, so it's a guard rail, not a substitute for Let's Encrypt's own limits. "Registered domain" is approximated from the last two labels (three under co.uk-style suffixes).

  • Only failures that reached validation count towards the failed-validation limit; a missing sudo rule or a missing nginx block doesn't.

  • History lives in issuance.json under MCP_STATE_DIR (default ~/.nginx-certbot-mcp/, mode 0600) and is pruned after 7 days. Set RATE_LIMIT_GUARD=off to disable the guard.

Environment variables

Variable

Used by

Notes

AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY

create_domain_record, delete_domain_record, create_txt_record, issue_wildcard_cert

Credentials for a Route-53-scoped IAM user — no other AWS permissions needed

ROUTE53_HOSTED_ZONE_ID

create_domain_record, delete_domain_record, create_txt_record

Find with aws route53 list-hosted-zones-by-name --dns-name julcap.net

AWS_DEFAULT_REGION

Same as above, plus issue_wildcard_cert

Optional — Route 53 is global, but the AWS SDK/boto3 still need a signing region; defaults to us-east-1

AUDIT_LOG_PATH

All mutating tools

Optional — audit log file; default ~/.nginx-certbot-mcp/audit.jsonl, off disables. See Audit log

MCP_MODE

All tools

Optional — readwrite (default) or readonly. See Read-only mode

MCP_ENABLED_TOOLS

All tools

Optional — comma-separated tool names / * patterns to expose; default all

ALLOWED_DOMAINS

All tools taking a domain

Optional — comma-separated example.com / *.example.com entries the agent may act on; default any. See Domain allowlist

RATE_LIMIT_GUARD

issue_cert, issue_wildcard_cert

Optional — off disables the production issuance guard

MCP_STATE_DIR

issue_cert, issue_wildcard_cert

Optional — where the guard keeps its issuance history; default ~/.nginx-certbot-mcp

AUDIT_LOG_READS

Read-only tools

Optional — true also audits read-only calls

Testing

Four layers, from "needs almost nothing" to "exercises everything":

1. Dependencies — npm run install:deps

Debian/Ubuntu only, idempotent. Installs nginx, certbot, python3-certbot-nginx, and python3-certbot-dns-route53 via apt if missing; for anything already installed, it only reports whether the version is current, since silently upgrading a package that might be serving traffic isn't this script's call to make. If certbot looks like a snap install (common — certbot's own docs recommend it over apt's often-outdated package), it also tries installing certbot-dns-route53 as a snap plugin, since an apt-installed plugin can be invisible to snap certbot's isolated Python environment. That's best-effort and additive, never a replacement for the apt package, so issue_wildcard_cert has a working path either way. Also reports your Node version against the >=20 that @aws-sdk/client-route-53 will eventually require.

2. Route 53 round trip — npm run test:dns

The only requirement is a working ROUTE53_HOSTED_ZONE_ID (+ AWS credentials) in .env. It discovers your zone's own domain from the hosted zone, creates a disposable CNAME under a random subdomain, verifies it (directly against Route 53, and best-effort via public DNS), then deletes it — cleanup runs even if a check in between fails, so a bad run can't leave an orphaned record.

3. Docker sandbox — real nginx + certbot, disposable

cp .env.example .env   # fill in AWS credentials + hosted zone ID
docker compose up -d --build
docker compose exec sandbox npm run inspect

The container runs systemd as PID 1, so sudo systemctl reload nginx and friends work exactly as they do in production (needs --privileged and a cgroup mount, which docker-compose.yml already sets up). nginx/ certbot/the plugins are installed via install-deps.sh, and the wrapper/sudoers via setup.sh, both at image build time. Tear down with docker compose down — nothing persists; every rebuild is a fresh install.

4. Automated tool-by-tool suite

cp .env.test.example .env.test   # AWS credentials + a domain you control
npm run test:tools                # against the Docker sandbox
npm run test:tools:host           # against this machine directly

Drives every tool over the real stdio JSON-RPC protocol and prints ✓/✗/– per tool. .env.test is separate from .env — read on the host and injected directly into each MCP server process the runner spawns, so the two files never need to match. Before touching anything it verifies your AWS credentials work and that TEST_DOMAIN is the zone's apex or a subdomain of it. Everything then runs under a random mcp-test-<random>.<TEST_DOMAIN> subdomain, self-cleans after each phase, and does a final best-effort cleanup regardless of pass/fail. Certificate issuance is opt-in — asked interactively, or pass --certs for a non-interactive run — since it hits real Let's Encrypt staging and adds a minute or two.

The two targets differ in exactly one way, issue_cert:

  • npm run test:tools (default) runs in the Docker sandbox, which isn't reachable from the internet, so issue_cert (HTTP-01) is always skipped — the cert scenario only exercises issue_wildcard_cert (DNS-01) and the renew/revoke/delete chain built on it.

  • npm run test:tools:host runs node dist/index.js directly on this machine. If this is the box your router actually forwards 80/443 to, the cert scenario tests issue_cert too (waiting up to 300s for the disposable CNAME to propagate first), and the renew/revoke/delete chain runs against that cert instead. It refuses to start unless passwordless sudo already works for the current user — i.e. npm run setup -- <user> was run for the user actually invoking it, not some other account. Everything this touches is real production state, not a sandbox.

Connecting a client

MCP Inspector — the fastest feedback loop for poking at a tool directly:

npm run inspect

Prints a URL with a session token. Run it against a real box, or the Docker sandbox (docker compose exec sandbox npm run inspect).

Claude Desktop / claude.ai — add to your MCP client config:

{
  "mcpServers": {
    "nginx-certbot": {
      "command": "node",
      "args": ["/absolute/path/to/nginx-certbot-mcp/dist/index.js"]
    }
  }
}

Or against the running Docker sandbox:

{
  "mcpServers": {
    "nginx-certbot-sandbox": {
      "command": "docker",
      "args": ["exec", "-i", "nginx-certbot-mcp-sandbox", "node", "dist/index.js"]
    }
  }
}

Diagnosing a site

When a site misbehaves, start with diagnose_site instead of calling the individual checks one by one. It runs, in parallel, and reports each as ok / warn / fail / skipped:

Check

Looks at

config

config exists, is enabled, server_name matches, upstream and SSL parsed out

nginx

service running, and nginx -t passes

dns

the domain resolves (CNAME, then A/AAAA)

upstream

the proxy_pass target accepts a TCP connection

certificate

a certbot cert covers the domain (wildcards included), days left, and that the config actually uses it

recent_errors

the latest nginx error-log lines mentioning the domain or its upstream

The result also has an overall healthy flag (no check failed — warnings and skipped checks don't count) and next_steps: the specific tools that would fix each problem, e.g. create_domain_record for a domain that doesn't resolve or rollback_site after a config that no longer passes nginx -t. A check that can't run (say, certbot isn't installed) is reported as skipped with the reason; it doesn't sink the rest.

It is read-only, so it's available in MCP_MODE=readonly, and it respects ALLOWED_DOMAINS.

Typical "add a new site" flow

  1. create_domain_record — point mysite.julcap.net at www.julcap.net

  2. (wait for DNS propagation)

  3. create_site — nginx serves the domain on port 80, reverse-proxied to the local service IP:port

  4. reload_nginx

  5. issue_cert — certbot validates via HTTP-01, updates nginx to redirect to 443

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines.

License

nginx-certbot-mcp is source-available under the Elastic License 2.0. You may use, modify, and redistribute the software. However, you may not provide a substantial portion of its functionality to third parties as a hosted or managed service.

For commercial licensing or partnership enquiries, contact the maintainer.

TODO

Planned, not yet implemented:

  • provision_site workflow tool — DNS record, nginx site, reload and certificate in one call, rolling back the steps already taken if a later one fails. Today the agent has to sequence the add-a-site flow itself.

  • Certificate expiry alerts — a warn_days threshold on check_cert_expiry and an optional webhook (Slack / Discord) for certificates that are close to expiring.

  • Per-site options in create_site — custom headers, client body size, rate limiting, basic auth, IP allowlist, HTTP→HTTPS redirect, HSTS, and a choice of named templates instead of the single default one.

  • More DNS providers — Cloudflare first, alongside Route 53 (certbot already has DNS plugins for it), so the DNS and DNS-01 tools aren't tied to AWS.

Available Tools

26 tools
check_cert_expiryA
Read-only

List every certbot-managed certificate on the box with its expiry date and days remaining, via certbot certificates. Read-only. Covers all certs certbot knows about, not just domains with an active nginx site.

Inputs: no named parameters. Returns: certificates

check_dnsA
Read-only

Resolve a domain (CNAME first, then A/AAAA) against public resolvers (1.1.1.1, 8.8.8.8) rather than this box's own DNS, so the result matches what Let's Encrypt and the public internet see. Use before issue_cert / create_site to confirm a domain actually points where you expect. For confirming something is listening behind nginx, use check_upstream_health instead.

Inputs: domain (required). Returns: values, resolves, record_type

check_upstream_healthA
Read-only

TCP-probe an upstream host:port to confirm something is actually listening there, independent of nginx or DNS. Use to sanity-check an upstream before create_site, or to debug a 502 afterward. For confirming a public domain resolves, use check_dns instead.

Inputs: upstream_host (required), upstream_port (required), timeout_ms. Returns: message, reachable

create_domain_recordA
Idempotent

Upsert a Route 53 CNAME record pointing domain at target. Safe to call repeatedly - it's an upsert, not create-only. Run this before create_site / issue_cert and allow a few minutes for DNS propagation; issue_cert re-checks resolution itself, so it's safe to retry issue_cert if it reports the domain isn't resolving yet. For an ACME DNS-01 TXT challenge record, use create_txt_record instead.

Inputs: domain (required), target (required), ttl. Returns: message, success, change_id, change_status

create_siteA

Create a new nginx server block from the websocket-capable default template. Validates and test-renders (nginx -t) before touching live config, and rolls back automatically if the test fails. Does NOT reload nginx or request a certificate - follow with reload_nginx to go live, then issue_cert to get SSL. To point an existing site at a different upstream later, use update_site instead of recreating it. If a config for the domain already exists it is replaced - after being backed up (see rollback_site).

Inputs: domain (required), upstream_host (required), upstream_port (required). Returns: success, config_path, test_output, backup_created, +1 more

create_txt_recordA
Idempotent

Upsert a Route 53 TXT record - e.g. for an ACME DNS-01 challenge (_acme-challenge., as used by issue_wildcard_cert) or domain verification. Quotes the value automatically if the caller didn't. Clean up afterward with delete_txt_record. For a CNAME pointing a domain at an upstream, use create_domain_record instead.

Inputs: value (required), domain (required), ttl. Returns: message, success, change_id, change_status

delete_certA
DestructiveIdempotent

Delete a certificate's files from certbot's local store. Destructive - requires confirm:true. Does not revoke the certificate first - if it may be compromised, call revoke_cert before this. Any nginx config still referencing the deleted files will fail to reload afterward.

Inputs: domain (required), confirm. Returns: message, success

delete_domain_recordA
DestructiveIdempotent

Delete the Route 53 CNAME record for a domain. Destructive - requires confirm:true to actually act; without it, returns what would happen and changes nothing. Looks up the exact existing record first rather than guessing its TTL/value.

Inputs: domain (required), confirm. Returns: message, success, change_id, change_status

delete_siteA
DestructiveIdempotent

Disable, archive, and delete the nginx server block for a domain. Destructive - requires confirm:true to actually act; without it, returns what would happen. Does not touch any certbot certificate for the domain. Does NOT reload nginx - call reload_nginx afterward. The archived copy can be brought back with restore_site.

Inputs: domain (required), confirm. Returns: message, success, reload_required

delete_txt_recordA
DestructiveIdempotent

Delete the Route 53 TXT record for a domain - e.g. to clean up an ACME DNS-01 challenge record left behind by create_txt_record or issue_wildcard_cert. Destructive - requires confirm:true to actually act; without it, returns what would happen and changes nothing. Looks up the exact existing record first rather than guessing its TTL/value. For a CNAME record, use delete_domain_record instead.

Inputs: domain (required), confirm. Returns: message, success, change_id, change_status

diagnose_siteA
Read-only

One-call health report for a domain: whether its nginx config exists and is enabled, whether nginx is running and passes nginx -t, whether the domain resolves, whether the upstream accepts TCP connections, whether a certificate covers it (and how long is left), and recent nginx error-log lines mentioning the site or its upstream. Read-only. Returns per-check status (ok/warn/fail/skipped), an overall healthy flag, and next_steps naming the tools that would fix each problem. Start here when a site is misbehaving instead of calling the individual check_* tools one by one.

Inputs: domain (required). Returns: checks, domain, healthy, summary, +1 more

get_nginx_statusA
Read-only

Report whether the nginx service is active (via systemctl) and its version string. Read-only.

Inputs: no named parameters. Returns: running, version

get_site_configA
Read-only

Get the raw, unparsed nginx config file for one domain from sites-available. Throws if no config exists for that domain - call list_sites first if you're not sure it exists.

Inputs: domain (required). Returns: domain, raw_config

issue_certA

Request a certificate via certbot --nginx (HTTP-01 validation). Requires an nginx server block for domain to already exist (create_site) - certbot's nginx plugin edits that existing sites-available config in place, adding an SSL server block and an HTTP->HTTPS redirect; it does not create a new site from scratch, and it reloads nginx itself on success (no separate reload_nginx call needed). Pre-checks that the domain resolves and fails fast with guidance if not, avoiding a wasted attempt against Let's Encrypt's rate limits. Defaults to Let's Encrypt staging, which issues browser-untrusted certs but is exempt from rate limits - pass staging:false only when you're ready for a real, publicly CT-logged certificate: production Let's Encrypt enforces real per-domain issuance rate limits (a handful of certs per week), and a mis-issued cert isn't silently undone - call revoke_cert if you need to invalidate one. A local guard also refuses production requests that would exceed Let's Encrypt's duplicate-certificate, failed-validation or per-domain limits, reporting when to retry. For a *.domain wildcard, use issue_wildcard_cert instead - HTTP-01 can't validate wildcards.

Inputs: domain (required), email, staging. Returns: success, dns_check, certbot_output, rate_limit_note

issue_wildcard_certA

Request a wildcard certificate (domain and *.domain) via certbot --dns-route53 (DNS-01 validation, required since HTTP-01 can't prove ownership of a wildcard). Requires the certbot-dns-route53 plugin installed on the box and AWS credentials in the environment (see README) - fails fast with guidance if credentials are missing. Defaults to staging; a local guard refuses production requests that would exceed Let's Encrypt's rate limits, reporting when to retry. For a single non-wildcard domain, use issue_cert instead.

Inputs: domain (required), email, staging. Returns: success, certbot_output, rate_limit_note

list_archived_sitesA
Read-only

List archived nginx configs created by delete_site, newest first. Feed a filename from here into restore_site's archive_filename to restore a specific archive instead of the newest.

Inputs: domain. Returns: archives

list_site_backupsA
Read-only

List the automatic backups of site configs, newest first. A backup is taken of the existing config just before create_site, update_site, restore_site or rollback_site changes it (the newest 10 per domain are kept). Feed a filename from here into rollback_site's backup_filename to return to a specific version instead of the newest. Not the same as list_archived_sites, which holds configs removed by delete_site.

Inputs: domain. Returns: backups

list_sitesA
Read-only

List every nginx server block currently in sites-enabled, with domain, upstream, and whether SSL looks configured. Read-only - parses config files directly, does not shell out to nginx. Use get_site_config for one domain's full raw config.

Inputs: no named parameters. Returns: sites

prune_archivesA
DestructiveIdempotent

Delete archived site configs (from delete_site) older than a threshold. Destructive - requires confirm:true to actually act; without it, lists what would be deleted and changes nothing. Continues past individual failures and reports how many actually got removed.

Inputs: confirm, older_than_days. Returns: pruned, message, success

reload_nginxA
Idempotent

Run nginx -t and reload the live service only if the config test passes - never reloads a broken config. Call this after create_site, delete_site, or restore_site to apply the change; those tools do not reload automatically.

Inputs: no named parameters. Returns: hint, success, test_output

renew_certA

Run certbot renew, optionally scoped to one cert via --cert-name. Defaults to --dry-run (simulates against Let's Encrypt staging without touching the live cert or rate limit) - pass dry_run:false only when you mean to actually renew. Always disables certbot's random pre-renewal sleep so the call returns synchronously.

Inputs: domain, dry_run. Returns: success, certbot_output

restore_siteA
Destructive

Restore a domain's nginx config from its most recent archive (created by delete_site) and enable it. Destructive to any current config for that domain (which is backed up first, see rollback_site) - requires confirm:true. Test-renders before enabling and rolls back automatically if that fails. Does NOT reload nginx - call reload_nginx afterward.

Inputs: domain (required), confirm, archive_filename. Returns: message, success, reload_required

revoke_certA
Destructive

Revoke a certificate with Let's Encrypt (e.g. after a key compromise) - the CA distrusts it immediately, browser-wide, for any site still serving it. Destructive and effectively irreversible - requires confirm:true. Leaves the cert files on disk; follow with delete_cert to remove them.

Inputs: domain (required), confirm. Returns: message, success

rollback_siteA
Destructive

Undo a config change: replace a site's current nginx config with a backup taken by create_site, update_site, restore_site or a previous rollback_site (see list_site_backups). Defaults to the newest backup, i.e. the config as it was before the last change. The current config is backed up first, so calling this again flips back. Requires confirm:true. Test-renders before keeping the result and leaves the current config in place if nginx -t fails. Does NOT reload nginx - call reload_nginx afterward.

Inputs: domain (required), confirm, backup_filename. Returns: message, success, reload_required

tail_site_logsA
Read-only

Tail nginx's access or error log (capped at 1000 lines). domain is a best-effort substring filter, not a true per-vhost filter - see the result's note.

Inputs: log_type (required), lines, domain. Returns: note, lines, success

update_siteA
Idempotent

Update an existing site's upstream by rewriting its proxy_pass directive(s) in place - everything else in the config, including any SSL server block issue_cert/certbot added, is left untouched. Fails if the domain has no existing config (use create_site instead) or has no proxy_pass directive to update. Test-renders before keeping the change and rolls back automatically if nginx -t fails. The previous config is backed up first, so a bad-but-valid change can be undone later with rollback_site. Does NOT reload nginx - call reload_nginx afterward.

Inputs: domain (required), upstream_host (required), upstream_port (required). Returns: success, test_output, backup_created, reload_required

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 26 tools

    Disambiguation4/5

    Most tools have clearly distinct resource-action targets, and descriptions frequently cross-reference the correct alternative when two tools could be confused. The main ambiguities are restore_site vs rollback_site (both restore saved configs, just from different sources) and create_site's replace-existing behavior overlapping with update_site.

    Naming Consistency5/5

    Every tool follows a consistent snake_case verb_noun pattern: list_sites, create_site, delete_cert, issue_cert, check_dns, reload_nginx, etc. Complementary pairs like create_domain_record/create_txt_record and revoke_cert/delete_cert show a predictable and readable convention.

    Tool Count3/5

    26 tools is above the comfortable range and even past the 16-25 heavy band, making the surface feel large. However, the count is largely justified by covering three distinct subdomains—nginx site lifecycle, certbot certificate lifecycle, and Route53 DNS records—so it is heavy but not chaotic.

    Completeness4/5

    The tool set covers the full nginx site lifecycle (create, read, update, delete, restore, rollback, backups, logs, reload), certificate lifecycle (issue, renew, revoke, delete, expiry), and DNS record management. Minor gaps exist: there is no tool to remove certificate references from an nginx config before delete_cert, and no general DNS record listing tool.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to manage Nginx Proxy Manager instances through natural language, covering 28 tools for proxy hosts, certificates, streams, and more.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables conversational management of Nginx Proxy Manager, including reverse-proxy routing, TLS certificates, access lists, and stream forwards, with built-in safety guardrails for production use.
      1
      MIT