nginx-certbot-mcp
This server lets an AI agent manage production web infrastructure (nginx reverse proxies, DNS records, and Let's Encrypt certificates) through scoped, auditable MCP tools, without giving root shell access.
Inspect infrastructure: List nginx sites, view raw configs, check cert expiry, resolve DNS, probe upstream health, get nginx status, tail logs, list archives/backups, and run a full site diagnosis with suggested fixes.
Manage DNS (Route 53): Create/update or delete CNAME records (for pointing domains), and create/delete TXT records (e.g., for ACME DNS-01 challenges).
Manage nginx sites: Create new sites from a template, update an existing site's upstream, delete/site (with archive), restore from archive, rollback config changes, prune old archives, and reload nginx only if config test passes.
Manage certificates: Issue certificates via HTTP-01 or DNS-01 (including wildcards), renew certificates (dry-run by default), revoke certificates, delete certificate files, and benefit from a production rate-limit guard.
Safety controls: Read-only mode, tool allowlist, domain allowlist, per-tool confirmation gates, automatic config backups, audit logging, and staging-by-default for certificate issuance.
Provides tools for reading nginx configuration, managing reverse proxy server blocks, reloading nginx, and issuing/renewing SSL certificates via certbot.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@nginx-certbot-mcp check the SSL cert expiry for example.com"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
nginx-certbot-mcp
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

Related MCP server: npm-mcp
Tools
All 26 are implemented and exercised against real infrastructure — see Testing.
Tool | Description |
| List configured nginx server blocks with domain, upstream, and SSL status |
| Raw nginx config for one domain |
| List certbot-managed certs and days until expiry |
| Resolve a domain (CNAME, then A/AAAA) against public resolvers |
| TCP probe of an upstream |
| Whether nginx is running, plus its version |
| One-call health report for a domain: config, nginx, DNS, upstream, certificate, recent errors — with suggested next tools |
| Tail access/error logs, capped at 1000 lines |
| List configs archived by |
| List the automatic pre-change backups of site configs |
| Upsert a Route 53 CNAME |
| Delete a Route 53 CNAME — |
| Upsert a Route 53 TXT record, e.g. for ACME DNS-01 |
| Delete a Route 53 TXT record — |
| Create a websocket-capable nginx server block from the default template |
| Rewrite an existing site's |
| Disable, archive, and delete a server block — |
| Re-enable a site from its newest (or a chosen) archive — |
| Undo a config change by restoring the newest (or a chosen) backup — |
| Delete archives older than N days — |
|
|
| Issue via HTTP-01 ( |
| Issue |
|
|
| Revoke with Let's Encrypt, leaving the files in place — |
| Remove a cert's files from certbot's store — |
Setup
npm install
npm run build
npm run setup -- mcpuserRun 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:
/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>orlog {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, forrestore/remove-archive/restore-backup, the archive or backup filename) itself, independent of the Node-side validation./etc/sudoers.d/nginx-mcp— grants<user>passwordless sudo on exactlynginx -t,systemctl reload nginx,systemctl is-active --quiet nginx,certbot, and the wrapper above. Nothing broader. It also keepsAWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY/AWS_DEFAULT_REGIONthrough sudo (which strips the environment by default) socertbot --dns-route53can see them forissue_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
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 recordcertbot-dns-route53creates 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(mode0600); override withAUDIT_LOG_PATH, or setAUDIT_LOG_PATH=offto 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=trueto include them.The file grows forever; point
logrotateat 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_MODEisreadwrite(default) orreadonly. Read-only mode drops every tool that changes state — DNS, nginx config, certificates, reloads.MCP_ENABLED_TOOLSis 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.commatches exactly that name;*.example.commatches 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
domainargument, read-only tools included, and to Route 53 record names (_acme-challenge.a.example.commatches*.example.com).issue_wildcard_certforexample.comalso covers*.example.com, so both must be allowed.Listings (
list_sites,check_cert_expiry,list_archived_sites) only show in-scope domains, andprune_archivesonly touches in-scope archives.renew_certandtail_site_logsnormally act on everything whendomainis omitted; with an allowlist they require one.Refused calls return a
Denied by policyerror and are written to the audit log with outcomedenied.
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_backupsshows the snapshots, newest first;rollback_siterestores the newest one by default (the config as it was before the last change) or a chosenbackup_filename. It needsconfirm: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 thebackupaction.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_nginxstill only reloads a config that passesnginx -t; when it refuses, itshintpoints atrollback_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.jsonunderMCP_STATE_DIR(default~/.nginx-certbot-mcp/, mode0600) and is pruned after 7 days. SetRATE_LIMIT_GUARD=offto disable the guard.
Environment variables
Variable | Used by | Notes |
|
| Credentials for a Route-53-scoped IAM user — no other AWS permissions needed |
|
| Find with |
| Same as above, plus | Optional — Route 53 is global, but the AWS SDK/boto3 still need a signing region; defaults to |
| All mutating tools | Optional — audit log file; default |
| All tools | Optional — |
| All tools | Optional — comma-separated tool names / |
| All tools taking a | Optional — comma-separated |
|
| Optional — |
|
| Optional — where the guard keeps its issuance history; default |
| Read-only tools | Optional — |
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 inspectThe 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 directlyDrives 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, soissue_cert(HTTP-01) is always skipped — the cert scenario only exercisesissue_wildcard_cert(DNS-01) and the renew/revoke/delete chain built on it.npm run test:tools:hostrunsnode dist/index.jsdirectly on this machine. If this is the box your router actually forwards 80/443 to, the cert scenario testsissue_certtoo (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 inspectPrints 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 exists, is enabled, |
| service running, and |
| the domain resolves (CNAME, then A/AAAA) |
| the |
| a certbot cert covers the domain (wildcards included), days left, and that the config actually uses it |
| 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
create_domain_record— pointmysite.julcap.netatwww.julcap.net(wait for DNS propagation)
create_site— nginx serves the domain on port 80, reverse-proxied to the local service IP:portreload_nginxissue_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_siteworkflow 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_daysthreshold oncheck_cert_expiryand 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 toolscheck_cert_expiryARead-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_dnsARead-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_healthARead-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_recordAIdempotent
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_recordAIdempotent
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_certADestructiveIdempotent
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_recordADestructiveIdempotent
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_siteADestructiveIdempotent
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_recordADestructiveIdempotent
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_siteARead-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_statusARead-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_configARead-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_sitesARead-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_backupsARead-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_sitesARead-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_archivesADestructiveIdempotent
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_nginxAIdempotent
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_siteADestructive
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_certADestructive
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_siteADestructive
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_logsARead-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_siteAIdempotent
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
Scored across 26 tools
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.
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.
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.
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
Related MCP Connectors
Read RunCloud servers, web apps, databases and logs; deploy, restart services, renew SSL.
Linux server administration over OAuth MCP: shell, Docker, systemd, files and monitoring.
Read Kinsta sites, environments, backups, logs and analytics; clear caches, restart PHP, back up.
Deploy services, add databases, run agents, read logs, check vulnerabilities and publish pages.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage Nginx Proxy Manager instances through natural language, covering 28 tools for proxy hosts, certificates, streams, and more.MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage Nginx Proxy Manager, including proxy hosts, SSL certificates, streams, and more.4 npmISC
- AlicenseBqualityCmaintenanceEnables AI agents to manage Nginx Proxy Manager (reverse proxies, streams, redirects, and Let's Encrypt certificates) through natural language commands.3023 npmMIT
- AlicenseNot gradedqualityDmaintenanceEnables 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.1MIT