porctl — CLI e MCP Server para Porkbun
maxdubrinsky/porctl
Gerencie domínios e DNS Porkbun por CLI ou via MCP, com editor visual
Ver no GitHubCliente de linha de comando e servidor MCP para gerenciar domínios, DNS, SSL e infraestrutura de domínios via API Porkbun. Inclui editor de zona tipo Terraform (dns edit) que abre registros DNS no seu editor favorito, aplica plano de mudanças revisado, e expõe funcionalidades read-only via MCP para agentes Claude.
Instalação
npx convez-ai maxdubrinsky/porctl1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automação de gerenciamento de domínios e DNS em pipelines DevOps
- Integração de Claude e agentes de IA com controle de domínios Porkbun
- Edição interativa de registros DNS com diff e plan antes de aplicar
- Scripting e infraestrutura como código para gerência de zona DNS
Veredito

Ferramenta sólida e bem pensada para operadores que usam Porkbun. O MCP server é seguro por design (read-only, sem risco de transferência de domínio) e o fluxo de edição dns é prático. Recomendado para quem já usa Porkbun e quer automação ou integração com Claude.
README
A tradução para o português deste README ainda está na fila.
porctl
A fast, scriptable command-line client and MCP server for the Porkbun domain API.
Manage domains, DNS, nameservers, URL forwarding, glue records, DNSSEC, and SSL bundles from your terminal — with a Terraform-style dns edit that opens your zone in $EDITOR and applies a reviewed plan.
Features
- Full Porkbun coverage — domains, DNS, nameservers, URL forwarding, glue records, DNSSEC, SSL, pricing.
dns edit— open a domain's DNS as a zone file (or YAML) in$EDITOR, then diff, plan, and apply. Records keep their IDs across edits; no churn.- Two output formats — aligned tables by default,
-o jsoneverywhere for scripting andjq. - MCP server built in —
porctl mcpexposes read-only Porkbun tools over stdio to any MCP client (Claude, etc.). - Safe by design — the underlying API can't move money or transfer a domain out, so an agent with your keys can't drain your account. See Security.
- Single static binary — no runtime, no config files. Credentials via flags or env.
Install
Homebrew (macOS):
brew install maxdubrinsky/tap/porctl
Or with the Go toolchain (any platform):
go install go.rpc.cafe/porctl/cmd/porctl@latest
Or download a prebuilt archive from the releases page.
Verify:
porctl --version
porctl ping
Authentication
- Create an API key pair at porkbun.com/account/api.
- Enable API access per domain — Porkbun disables it by default. In the domain's controls, toggle "API Access" on for every domain you want
porctlto manage. (pingandpricingwork without it; everything else needs it.) - Provide the keys to
porctlvia environment variables (recommended):
export PORKBUN_API_KEY=pk1_xxxxxxxx
export PORKBUN_SECRET_KEY=sk1_xxxxxxxx
or per-invocation flags:
porctl ping --api-key pk1_xxxxxxxx --secret-key sk1_xxxxxxxx
Without credentials, authenticated commands print a clear error pointing you back here.
Quick start
porctl ping # verify creds, show your public IP
porctl domain list # all domains in the account
porctl dns list example.com # DNS records for a domain
porctl dns edit example.com # open the zone in $EDITOR and apply changes
porctl dns list example.com -o json | jq # machine-readable output
Command reference
Run porctl <command> --help for full flag listings. Every command accepts the global flags and -o json.
| Command | What it does | Example |
|---|---|---|
ping | Verify credentials and show your public IP | porctl ping |
pricing [tld...] | Default registration / renewal / transfer pricing (no creds) | porctl pricing com io dev |
domain list | List all domains in the account (--labels to include labels) | porctl domain list |
domain check <domain> | Check availability and price for a domain | porctl domain check example.com |
domain get <domain> | Metadata for one domain (status, expiry, locks) | porctl domain get example.com |
domain autorenew <domain> <on|off> | Toggle auto-renew | porctl domain autorenew example.com on |
ns get <domain> | Show authoritative nameservers | porctl ns get example.com |
ns set <domain> <ns>... | Replace nameservers | porctl ns set example.com curitiba.ns.porkbun.com fortaleza.ns.porkbun.com |
dns list <domain> | List DNS records (-t/-n to filter) | porctl dns list example.com -t A |
dns get <domain> <id> | Show one record by ID | porctl dns get example.com 123456 |
dns create <domain> | Create a record | porctl dns create example.com -t A -n www --content 1.2.3.4 |
dns update <domain> <id> | Update a record (only flags you pass change) | porctl dns update example.com 123456 --content 5.6.7.8 |
dns edit <domain> | Edit the whole zone in $EDITOR with a plan/apply | porctl dns edit example.com |
dns delete <domain> <id> | Delete a record by ID | porctl dns delete example.com 123456 |
dnssec list <domain> | List registry DNSSEC (DS) records | porctl dnssec list example.com |
dnssec add <domain> | Add a DS record | porctl dnssec add example.com --key-tag 12345 --algorithm 13 --digest-type 2 --digest ABCD… |
dnssec delete <domain> <keytag> | Delete a DS record by key tag | porctl dnssec delete example.com 12345 |
forward list <domain> | List URL forwards | porctl forward list example.com |
forward add <domain> | Add a URL forward | porctl forward add example.com --subdomain www --to https://example.org --type permanent |
forward delete <domain> <id> | Delete a URL forward by ID | porctl forward delete example.com 98765 |
glue list <domain> | List glue records (host objects) | porctl glue list example.com |
glue set <domain> <host> <ip>... | Create a glue record | porctl glue set example.com ns1 1.2.3.4 2001:db8::1 |
glue update <domain> <host> <ip>... | Replace a glue record's IPs | porctl glue update example.com ns1 5.6.7.8 |
glue delete <domain> <host> | Delete a glue record | porctl glue delete example.com ns1 |
ssl get <domain> | Download the issued SSL bundle | porctl ssl get example.com --out-dir ./certs |
mcp | Run the MCP server over stdio | porctl mcp |
domain/forward/list accept aliases (domains, forwarding, ls, rm). Mutating commands (delete, dns edit) prompt for confirmation; pass -y/--yes to skip.
Creating records
porctl dns create example.com --type A --name www --content 1.2.3.4
porctl dns create example.com --type MX --content mail.example.com --prio 10
porctl dns create example.com --type TXT --content "v=spf1 -all"
Supported types: A, AAAA, CNAME, MX, TXT, NS, ALIAS, SRV, TLSA, CAA. Use @ (or omit --name) for the apex, * for a wildcard. TTL defaults to the account minimum (~600s).
SSL bundles
porctl ssl get example.com # print the certificate chain to stdout
porctl ssl get example.com --out-dir certs # write fullchain.pem, privkey.pem (0600), pubkey.pem
porctl ssl get example.com -o json # full bundle incl. private key as JSON
The private key is never printed to stdout in table mode — only written to disk (with --out-dir) or emitted with -o json.
dns edit — the killer feature
porctl dns edit <domain> pulls the live zone, opens it in your editor, then computes a diff and shows a plan before touching anything. Records are matched by ID, so editing a line updates it, deleting a line deletes it, and a new line (with no ID) creates it. IDs are never churned.
porctl dns edit example.com # zone-file buffer (default)
porctl dns edit example.com --format yaml # YAML buffer instead
porctl dns edit example.com --dry-run # show the plan, apply nothing
porctl dns edit example.com --file zone.txt --yes # apply a buffer non-interactively (CI)
porctl dns edit example.com -o json # print the plan as JSON (does not apply)
The editor is $VISUAL, then $EDITOR, then vi.
Sample buffer (zone format)
; example.com — edit, save and close to apply.
;
; One record per line: NAME TTL TYPE CONTENT
; @ = apex, * = wildcard. MX/SRV priority goes first in CONTENT (e.g. "10 mail.example.com.").
; Lines ending in ; #<id> are existing records — keep the id intact.
; Add a line (no id) to create. Remove a line to delete. Change a line to update.
;
@ 600 A 1.2.3.4 ; #301000001
www 600 CNAME example.com ; #301000002
@ 600 MX 10 mail.example.com ; #301000003
@ 600 TXT "v=spf1 -all" ; #301000004
Say you change the apex A to 5.6.7.8, add an AAAA, and delete the CNAME:
@ 600 A 5.6.7.8 ; #301000001
@ 600 AAAA 2001:db8::1
@ 600 MX 10 mail.example.com ; #301000003
@ 600 TXT "v=spf1 -all" ; #301000004
Resulting plan
~ update @ A 5.6.7.8 #301000001
+ create @ AAAA 2001:db8::1
- delete www CNAME example.com #301000002
Plan: 1 to add, 1 to change, 1 to destroy.
Apply 3 change(s) to example.com? [y/N]
Confirm, and porctl applies creates, then updates, then deletes, printing each result. The YAML buffer (--format yaml) carries the same information as a list of records with id, name, type, content, ttl, prio, and notes fields — omit id to create, drop an item to delete. (--format is inferred from a .yaml/.yml extension when you use --file.)
Output formats
table(default) — aligned, human-readable columns.-o json— structured JSON for every command, ready forjqand scripts.
porctl domain list -o json | jq -r '.[].domain'
porctl dns list example.com -t A -o json | jq '.[] | {name, content}'
Global flags
| Flag | Description |
|---|---|
--api-key | API key (env PORKBUN_API_KEY) |
--secret-key | Secret key (env PORKBUN_SECRET_KEY) |
-o, --output | table (default) or json |
--timeout | Request timeout (default 30s) |
--ipv4 | Use the IPv4-only API host |
--base-url | Override the API base URL |
MCP server
porctl mcp runs a Model Context Protocol server over stdio, exposing read-only Porkbun operations as tools. Point any MCP client at it and pass your credentials in the launch environment.
Client configuration
{
"mcpServers": {
"porkbun": {
"command": "porctl",
"args": ["mcp"],
"env": {
"PORKBUN_API_KEY": "pk1_xxxxxxxx",
"PORKBUN_SECRET_KEY": "sk1_xxxxxxxx"
}
}
}
}
(Use the absolute path to porctl, e.g. ~/go/bin/porctl, if it isn't on the client's PATH.)
Tools (all read-only)
| Tool | Description |
|---|---|
porkbun_ping | Verify credentials and return the caller's public IP. |
porkbun_pricing_get | Default domain pricing (registration, renewal, transfer) keyed by TLD. |
porkbun_domain_list | List all domains, with status, expiry, and settings. |
porkbun_domain_get | Metadata for one domain: status, expiry, auto-renew, WHOIS privacy, security lock, API access. |
porkbun_domain_check | Check whether a domain is available to register, with pricing. |
porkbun_ns_get | Authoritative nameservers for a domain. |
porkbun_dns_list | List DNS records, optionally filtered by type and/or subdomain. |
porkbun_dns_get | A single DNS record by its numeric ID. |
porkbun_dnssec_list | Registry DNSSEC (DS / key data) records for a domain. |
porkbun_forward_list | Active URL forwards, with destination, redirect type, path/wildcard settings. |
porkbun_glue_list | Glue records (host objects) with their IPv4/IPv6 addresses. |
porkbun_ssl_retrieve | The issued SSL bundle (chain, private key, public key) for a domain. |
The MCP surface is deliberately read-only — it exposes no record-mutating or money operations. Use the CLI directly for changes.
Security / handing keys to an agent
A growing reason to use porctl is to let an AI agent manage your DNS. Giving any automated system credentials is risky, so it's worth being precise about the blast radius.
The Porkbun API cannot spend money you don't already have, and cannot exfiltrate a domain. Specifically, via the API an attacker (or a misbehaving agent) cannot add funds, charge a card, or transfer a domain out of your account. The most expensive thing the API can do — renewing or registering — draws from your existing account credit balance. So your maximum exposure is capped at whatever balance is sitting in the account.
To make spend structurally impossible:
- Keep your account credit balance at $0.
- Turn auto-topup off so nothing can refill it.
With $0 credit and no top-up, there is simply nothing for an API caller to spend, regardless of what keys leak.
On top of that, porctl itself exposes no money operations — there are no buy/renew/transfer commands in the CLI, and the MCP server is read-only. The worst a porctl-driven agent can do is misconfigure DNS, which is recoverable. Still, scope keys to only the domains you intend to manage (API access is per-domain), and prefer the read-only MCP server when an agent only needs to look.
Forthcoming: a
--read-onlymode to disable all mutations on the CLI, and aporctl accountcommand to inspect your balance and top-up settings at a glance.
License
Released under the MIT License.