Skip to main content
Glama
julcap

nginx-certbot-mcp

by julcap
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

issue_cert

Obtain a Let's Encrypt SSL certificate for an existing nginx site, enabling HTTPS and HTTP-to-HTTPS redirect. Uses staging by default; set staging:false for production certificates.

Instructions

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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
emailNoContact email registered with the Let's Encrypt account, used for renewal-failure and expiry notices. Omitted registers with --register-unsafely-without-email, so Let's Encrypt cannot warn you if a future automated renewal fails.
domainYesDomain to request a certificate for. Must already resolve (see check_dns) and already have an nginx server block from create_site - certbot edits that existing config rather than creating one.
stagingNoTrue (default) uses Let's Encrypt's staging CA - browser-untrusted certs, but exempt from production rate limits; use for testing the flow. False requests a real, browser-trusted cert and counts against production rate limits.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
successYes
dns_checkNoPresent only when the DNS pre-check failed, before certbot was even invoked
certbot_outputYesRaw combined stdout/stderr from the certbot CLI invocation, on success or failure
rate_limit_noteNoSet when the local rate-limit guard refused a production request (with when to retry), or when a Let's Encrypt production limit is close

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.1.2
    • addedOutput schema / properties / rate_limit_note
      Added value: +{
+  "description": "Set when the local rate-limit guard refused a production request (with when to retry), or when a Let's Encrypt production limit is close",
+  "type": "string"
+}
  2. Changed5 schema fields changedv0.1.1
    • removedInput schema / additionalProperties
      Removed value: -false
    • addedInput schema / properties / domain / description
      Added value: +"Domain to request a certificate for. Must already resolve (see check_dns) and already have an nginx server block from create_site - certbot edits that existing config rather than creating one."
    • addedInput schema / properties / email / description
      Added value: +"Contact email registered with the Let's Encrypt account, used for renewal-failure and expiry notices. Omitted registers with --register-unsafely-without-email, so Let's Encrypt cannot warn you if a future automated renewal fails."
    • addedInput schema / properties / staging / description
      Added value: +"True (default) uses Let's Encrypt's staging CA - browser-untrusted certs, but exempt from production rate limits; use for testing the flow. False requests a real, browser-trusted cert and counts against production rate limits."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "certbot_output": {
+      "description": "Raw combined stdout/stderr from the certbot CLI invocation, on success or failure",
+      "type": "string"
+    },
+    "dns_check": {
+      "additionalProperties": false,
+      "description": "Present only when the DNS pre-check failed, before certbot was even invoked",
+      "properties": {
+        "record_type": {
+          "description": "Only present when resolves is true",
+          "enum": [
+            "A",
+            "AAAA",
+            "CNAME"
+          ],
+          "type": "string"
+        },
+        "resolves": {
+          "type": "boolean"
+        },
+        "values": {
+          "description": "Resolved values (IPs, or the CNAME target); only present when resolves is true",
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        }
+      },
+      "required": [
+        "resolves"
+      ],
+      "type": "object"
+    },
+    "success": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "success",
+    "certbot_output"
+  ],
+  "type": "object"
+}
  3. First observedv0.1.0

TDQS

A5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds substantial behavioral context beyond the openWorldHint/destructiveHint annotations: it edits existing nginx config in place, adds an SSL block and redirect, reloads nginx automatically, pre-checks DNS, fails fast on resolution errors, and enforces rate-limit guards. It also clarifies that production certs are not silently undone and recommends revoke_cert if needed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but every sentence earns its place: prerequisites, operational behavior, failure handling, staging trade-offs, production risks, and the wildcard alternative are all covered without fluff. It is front-loaded with the core action and requirements.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a high-complexity tool with rate limits, config mutation, and lifecycle implications. The description covers prerequisites, side effects, failure modes, retry guidance, staging/production trade-offs, and alternatives. Since an output schema exists, return-value details are not needed in the description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Even though the schema already describes all three parameters at 100% coverage, the description enriches them further with real-world consequences: staging certs are browser-untrusted, production certs are CT-logged and rate-limited, omitted email registers without a contact for renewal warnings, and the domain must have an existing server block.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a precise verb and resource: requesting a certificate via certbot --nginx with HTTP-01 validation. It clearly distinguishes this from create_site (does not create a new site), reload_nginx (no separate call needed), and issue_wildcard_cert (for wildcard domains).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly says when to use this tool (standard domain cert via HTTP-01), when not to (wildcards should use issue_wildcard_cert), and the prerequisites (existing nginx server block from create_site, domain resolving via check_dns). It also explains staging vs. production usage with clear conditions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools