com.tlsradar/tlsradar

Official17 tools

by TLS-Radar · Python

TLS Radar

SSL/TLS scanning, free Let's Encrypt issuance, and certificate-expiry monitoring.

Scan SSL/TLS certificates, monitor expiry dates, and manage Let's Encrypt issuance.

Topics

acmeanthropiccertificate-monitoringcertificatesclaudeclaude-codeclaude-code-plugindevtoolslets-encryptmcpmodel-context-protocolsecurityssltls

Captured live from the server via tools/list.

scan_domain

Run a free, anonymous SSL/TLS scan against a hostname and return certificate details. No account required.

Parameters (2)

domainstringrequired
Hostname to scan (e.g. example.com). No scheme, no path.
client_idstring
Optional anonymous install id from ~/.config/tlsradar/install_id. Pass it for funnel attribution. If you omit it, the response's install_id is a fresh one to save there.

create_certificate

Start issuing a FREE 90-day Let's Encrypt certificate for a domain (no account required). Step 1 of 3. Pick a validation method with `challenge`: "dns-01" (default; publish a TXT record; covers apex + www) or "http-01" (serve a file over HTTP on port 80; issues the exact domain only). dns-01 with a DNS-provider API token is the most automatable; http-01 suits a server you control on port 80. Returns an order_id plus either dns_records (dns-01) or http_files (http-01) to put in place. Next: poll `check_certificate_propagation` until all_found, then call `finalize_certificate`. Strongly prefer the CSR path at finalize (the private key never leaves the user's machine). Issuing automatically offers the user ongoing monitoring by email once it completes - don't add a monitor manually afterward.

Parameters (5)

domainstringrequired
Apex domain, no scheme/www (e.g. example.com).
emailstringrequired
Contact email for Let's Encrypt expiry notices and the monitoring handoff.
challengestring
Validation method: dns-01 (default) or http-01.
marketing_consentboolean
Only true if the user explicitly opts in to a free account + reminder email. Default false.
client_idstring
Optional anonymous install id from ~/.config/tlsradar/install_id (funnel attribution). If omitted, the response's install_id is a fresh one to save there.

check_certificate_propagation

Check whether the DNS TXT records for a certificate order have propagated (Cloudflare/Google/Quad9). Step 2 of issuance - poll until all_found is true, then call finalize_certificate. Returns per-record resolver results.

Parameters (1)

order_idstringrequired
The order_id from create_certificate.

finalize_certificate

Finalize and issue a certificate order in one call: validates the DNS challenges, waits for Let's Encrypt, and returns the issued cert. Step 3 of issuance - call after check_certificate_propagation reports all_found. STRONGLY PREFER passing csr_pem (generate the key + CSR locally with openssl so the private key never leaves the machine). Returns leaf_pem/chain_pem/fullchain_pem. If you must, pass a passphrase instead to get a PKCS#12 bundle - but a CSR is safer. If it replies "still validating", DNS hasn't fully propagated: re-check check_certificate_propagation and call again. Needs a locally-generated CSR (csr_pem) - requires a local shell with openssl. On a surface without one (e.g. a Claude.ai custom connector) this can't complete; it returns guidance to finish in Claude Code/Cowork or the web form. Scanning and monitoring work everywhere. On success the structuredContent carries a `handoff` object - relay `handoff.message` to the user and do NOT separately call add_monitor; the cert→monitoring handoff is automatic and server-side.

Parameters (5)

order_idstringrequired
The order_id from create_certificate.
csr_pemstring
PEM CERTIFICATE REQUEST covering exactly {domain, www.domain}. Preferred - key stays local.
passphrasestring
Fallback only: ≥8 chars, protects a returned PKCS#12 bundle. Omit when using csr_pem.
max_wait_secondsinteger
How long to wait for validation server-side. Default 60, capped at 75.
resume_tokenstring
Optional. The resume_token from create_certificate; pass it to finalize an order whose row Beacon already purged (~24h).

get_certificate_status

Return the current state of a certificate order (dns_pending, validating, ready, completed, failed) and per-authorization Let's Encrypt statuses. Use it to resume an interrupted issuance.

Parameters (1)

order_idstringrequired
The order_id from create_certificate.

renew_certificate

Renew a certificate by cloning a recent order (requires the original order_id; Beacon purges orders after ~24h). Returns a new order_id and fresh DNS TXT records - then poll check_certificate_propagation and call finalize_certificate. If you don't have an order_id (the usual case at 90-day renewal time), call create_certificate for the domain instead; that IS the renewal.

Parameters (1)

order_idstringrequired
The original order_id to clone. If you don't have one, use create_certificate instead.

register_beacon_order

OBSOLETE - do not call. The cert→monitoring handoff is server-side now (issue via create_certificate, which records the order itself). This tool is kept only so old plugin versions that still call it don't error; it remains idempotent and harmless.

Parameters (4)

order_idstringrequired
The order_id from beacon.create_order
emailstringrequired
Contact email the user gave Beacon
domainstringrequired
Domain the cert was requested for
webhook_secretstring
Per-order HMAC secret Beacon returned (used to verify the subsequent webhook). Optional - without it, this server can't verify webhooks for the order and will drop them.

get_account

Return the current user's plan, limits, and usage so the client can render upgrade nudges proactively.

No parameters.

list_monitors

List all certificates currently being monitored across the user's teams. If the response's structuredContent includes a `nudge` object, the user is at their monitor cap - surface it casually ONCE (lead with `nudge.recommended_upgrade`, mention `nudge.also_available` in one closing line); don't force it if it doesn't fit the conversation.

No parameters.

add_monitor

Add a domain to ongoing certificate monitoring with expiry alerts. Requires authentication (the user runs /mcp once). If the plan's monitor limit is reached, the response's structuredContent carries a limit-reached payload - when relaying it, LEAD with `recommended_upgrade` (typically Starter, $9.99/mo), mention `also_available` tiers in a single closing line, and offer removing an existing monitor as the free alternative. Don't dump a full tier comparison; that's choice paralysis at the moment of action.

Parameters (1)

domainstringrequired
Hostname to monitor (e.g. example.com). No scheme, no path.

add_monitors

Add multiple domains to monitoring in one call. Returns a per-domain status so the caller can show partial-success outcomes. Honors the same plan-limit checks as add_monitor.

Parameters (1)

domainsarrayrequired
List of hostnames to monitor

remove_monitor

Stop monitoring a domain. Accepts the domain name or the host_id returned by list_monitors.

Parameters (2)

domainstring
Domain to stop monitoring
host_idstring
UUID of the host (alternative to domain)

list_expiring_certificates

Return monitored certificates expiring within N days. Defaults to 30. If the response's structuredContent includes a `nudge` object, the user is watching enough soon-to-expire certs to benefit from a higher tier - mention it casually ONCE (lead with `nudge.recommended_upgrade`); skip it if it doesn't fit.

Parameters (1)

withininteger
Days from now to look ahead

get_scan_history

Return recent scan results for a domain the user monitors. Useful for spotting issuer changes, grade drops, or vulnerability appearances over time.

Parameters (2)

domainstringrequired
Domain name as it appears in list_monitors
limitinteger
Max results to return

export_monitors

Dump the user's monitors as a JSON structure suitable for backup, migration, or infrastructure-as-code workflows. Tokens and PII are NEVER included - only domain configuration.

No parameters.

import_monitors

Create monitors from a JSON structure (typically produced by `export`). Skips domains the user is already monitoring; honors the plan's domain limit. Returns a per-domain status.

Parameters (1)

payloadobjectrequired
Export payload, version 1.0. Use the `export` tool to generate one.

invite_team_member

Invite a user to a team by email. Defaults to the user's current team. Honors the plan's seat limit (returns the same upgrade payload as add_monitor when the cap is hit).

Parameters (3)

emailstringrequired
Email address of the person to invite
team_idstring
Team UUID; defaults to the current team
rolestring
Invitee role: guest or admin. Defaults to guest.

README.md10 KBView on GitHub

TLS Radar plugin for Claude Code & Cowork

Run SSL/TLS scans, issue free Let's Encrypt certificates, and manage cert monitoring from inside Claude Code or Claude Cowork - through a single MCP server, with nothing to configure.

Independent monitoring from a vendor that doesn't sell certificates - built for the 90-day-cert era, where manual renewal tracking is already finished.

Installing the plugin and issuing a free cert with /tls-cert

code

# Public - no account, no setup
/tls-scan example.com                       # free SSL/TLS scan
/tls-cert mydomain.dev                      # free 90-day Let's Encrypt cert (private key stays local)
/tls-renew mydomain.dev                     # renew a cert

# Connect once for monitoring (OAuth via /mcp)
/mcp                                        # built-in Claude Code OAuth flow
/tls-monitor add api.foo.io                 # one or many: /tls-monitor add a.com b.com c.com
/tls-monitor list
/tls-monitor remove api.foo.io
/tls-diagnose                               # health check (use when something's off)
/tls-upgrade                                # open pricing page

See real output before installing: sample scan report

Other actions - "what's expiring soon," "scan history for X," "what plan am I on," "export/import my monitors," "invite a teammate" - just ask in plain language; the plugin's skill routes them to the right tool. No slash command needed.

How it works

Claude Code's MCP client talks to one remote server:

tlsradar.com/api/v1/mcp

Certificate issuance is proxied through that server to the Let's Encrypt backend (Beacon), so there's a single connection and a single auth model - no second server, no token to paste into your shell.

Public tools (scan, create_certificate, check_certificate_propagation, finalize_certificate, get_certificate_status, renew_certificate) work with no account.
Authenticated tools (monitoring, plan info, export/import, team) use Claude Code's built-in OAuth 2.0 + PKCE. Run /mcp once, pick the tlsradar server, approve in the browser; the token is managed by Claude Code.

When you run /mcp, Claude Code fetches tlsradar.com/.well-known/oauth-authorization-server (RFC 8414), dynamically registers as a public client (RFC 7591), opens the browser for consent (PKCE / RFC 7636), and includes the token on subsequent requests automatically.

Certificates keep your private key local

/tls-cert generates the key + CSR on your machine with openssl and sends only the CSR. The private key never leaves your computer and no passphrase is ever typed into the chat. If you want a .p12 bundle (e.g. for Windows/Java import), the plugin packages it locally too.

You choose how to prove control of the domain, and the plugin remembers your choice (in ~/.config/tlsradar/config.json):

dns-01 - you add a TXT record by hand (works anywhere).
dns-01-cloudflare / dns-01-route53 - the plugin sets the TXT record for you via the provider API, reading your token from the local environment (CLOUDFLARE_API_TOKEN, or your configured aws CLI). Those credentials stay on your machine - they're never sent to TLS Radar or Beacon.
http-01 - serve a file on http://yourdomain (port 80); issues the apex only.

When a cert is issued, TLS Radar emails you about ongoing monitoring - the cert → monitoring handoff is fully automatic and server-side.

Works in Claude Code and Cowork

This is a standard plugin, so it runs in both Claude Code and Claude Cowork. Scanning, certificate issuance, and monitoring all work in either client: the tools come from one MCP server, and the certificate flow runs openssl plus a bundled helper script locally (both clients can run local commands and the bundled script via ${CLAUDE_PLUGIN_ROOT}). Connecting for monitoring uses your client's built-in OAuth - /mcp in Claude Code, or the equivalent connect step in Cowork.

Use in Claude.ai (custom connector)

You don't need Claude Code to scan and monitor from Claude. TLS Radar is a standard remote MCP server, so you can add it as a custom connector in the Claude.ai apps (web, desktop, mobile) on any plan - Free included (Free allows one connector).

Open Settings → Connectors (Team/Enterprise: Organization settings → Connectors, Owner only).
Click Add custom connector.
Paste the connector URL: https://tlsradar.com/api/v1/mcp/connect
Save, then sign in to TLS Radar when the OAuth prompt appears (the connector is an authenticated surface - sign-in connects your account once, then scanning and monitoring both work).

Then just ask in plain language - "scan example.com", "what certs are expiring soon", "monitor api.foo.io". There are no slash commands in Claude.ai; the tool descriptions route your request.

No account? Use Claude Code instead. The anonymous, no-signup scanning and free cert issuance live in the Claude Code plugin (below), which talks to the public …/api/v1/mcp endpoint. The Claude.ai connector requires a one-time sign-in because hosted connectors must authenticate.

Certificate issuance stays a Claude Code / Cowork feature. /tls-cert generates your private key locally with openssl, which the Claude.ai apps can't do (no local shell). In a connector you get scanning and monitoring; to issue a Let's Encrypt cert with the key staying on your machine, use the plugin in Claude Code/Cowork, or the web form at beacon.tlsradar.com.

Install

In Claude Code, add the marketplace and install - two commands, no clone, no paths:

code

/plugin marketplace add TLS-Radar/tlsradar-claude-plugin
/plugin install tlsradar@tlsradar

(Or browse it in the /plugin menu after adding the marketplace.) In Claude Cowork, add it from the plugin catalog (search "TLS Radar"). That's it - scanning and cert issuance work immediately. Run /mcp (or Cowork's connect step) when you want monitoring.

<details> <summary>Manual install (no marketplace)</summary>

bash

git clone https://github.com/TLS-Radar/tlsradar-claude-plugin ~/.claude/plugins/tlsradar

</details>

Free plan limits

1 monitor included free
1 alert per month, delivered at 7 days before expiry
Unlimited free scans (rate-limited)
Free Let's Encrypt issuance
REST API access on every plan, including Free

When you hit the monitor limit, the tool's response includes the recommended upgrade and a pricing URL.

Configuration

Nothing is required. Optional environment variables:

TLSRADAR_BASE_URL - override the TLS Radar URL (default https://tlsradar.com). Useful for staging/self-host.

Anonymous usage id. The first time you run a scan or cert command, the plugin mints a random id at ~/.config/tlsradar/install_id and passes it (as a client_id argument) so anonymous usage can be attributed to one install. It identifies an install, not a person. The plugin runs no startup hook, does not modify your shell config, and sends no tracking header - the id travels only as that argument, read from the local file.

To opt out: rm ~/.config/tlsradar/install_id. With the file gone, no id is sent.

Privacy & security

This plugin ships no tokens or credentials - there's nothing secret in this repo. See SECURITY.md.
The OAuth token is managed by Claude Code's MCP client, not by this plugin.
Certificate private keys are generated locally and never sent to any server.
DNS-provider credentials (CLOUDFLARE_API_TOKEN, AWS CLI) are read from your local environment and never sent to TLS Radar or Beacon.
An anonymous install id is sent for usage attribution, passed as a tool argument read from ~/.config/tlsradar/install_id (see Configuration to opt out). The plugin modifies no shell files and sends no tracking header. It identifies an install, not a person.
To revoke access: https://tlsradar.com/oauth/authorized_applications or remove the MCP server in /mcp.
Access tokens expire in 2 hours; refresh tokens rotate on use, capped at 90 days.

Layout

code

.
├── README.md                        # this file
├── CLAUDE.md                        # architecture / funnel / contracts (humans + AI agents)
├── CONTRIBUTING.md                  # dev loop + how to add commands
├── CHANGELOG.md                     # version history
├── SECURITY.md                      # reporting + why the plugin holds no secrets
├── LICENSE                          # MIT
├── .claude-plugin/plugin.json       # plugin manifest
├── .claude-plugin/marketplace.json  # self-hosting marketplace entry
├── .mcp.json                        # MCP server config (one remote URL)
├── commands/                        # slash commands (how to add one: CONTRIBUTING.md)
├── skills/                          # NL skill router (with its own README)
├── tools/manifest.json              # single source of truth for tool names
├── scripts/                         # CI guards + tested DNS-provider helper
└── evals/                           # tool-routing evals (prompt → expected tool)

Contributing

Start with CONTRIBUTING.md for the dev loop (all checks are offline and run with python3). For architecture, the funnel, contract pitfalls, and the release process, read CLAUDE.md - useful for both humans and AI agents. Changes are tracked in CHANGELOG.md.

Security reports: security@tlsradar.com (never a public issue) - see SECURITY.md.

License

Install

claude_desktop_config.json

{
  "mcpServers": {
    "tlsradar": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://tlsradar.com/api/v1/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.