convez.ai
MCP ServerDevOps & InfraestruturaIntermediário
maxdubrinsky

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 GitHub
InicialPluginScore · de 0 a 100

Cliente 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/porctl

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
v0.1.0
Issues abertas
0
Contribuidores
1

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 json everywhere for scripting and jq.
  • MCP server built in — porctl mcp exposes 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

  1. Create an API key pair at porkbun.com/account/api.
  2. Enable API access per domain — Porkbun disables it by default. In the domain's controls, toggle "API Access" on for every domain you want porctl to manage. (ping and pricing work without it; everything else needs it.)
  3. Provide the keys to porctl via 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.

CommandWhat it doesExample
pingVerify credentials and show your public IPporctl ping
pricing [tld...]Default registration / renewal / transfer pricing (no creds)porctl pricing com io dev
domain listList all domains in the account (--labels to include labels)porctl domain list
domain check <domain>Check availability and price for a domainporctl 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-renewporctl domain autorenew example.com on
ns get <domain>Show authoritative nameserversporctl ns get example.com
ns set <domain> <ns>...Replace nameserversporctl 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 IDporctl dns get example.com 123456
dns create <domain>Create a recordporctl 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/applyporctl dns edit example.com
dns delete <domain> <id>Delete a record by IDporctl dns delete example.com 123456
dnssec list <domain>List registry DNSSEC (DS) recordsporctl dnssec list example.com
dnssec add <domain>Add a DS recordporctl dnssec add example.com --key-tag 12345 --algorithm 13 --digest-type 2 --digest ABCD…
dnssec delete <domain> <keytag>Delete a DS record by key tagporctl dnssec delete example.com 12345
forward list <domain>List URL forwardsporctl forward list example.com
forward add <domain>Add a URL forwardporctl forward add example.com --subdomain www --to https://example.org --type permanent
forward delete <domain> <id>Delete a URL forward by IDporctl 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 recordporctl glue set example.com ns1 1.2.3.4 2001:db8::1
glue update <domain> <host> <ip>...Replace a glue record's IPsporctl glue update example.com ns1 5.6.7.8
glue delete <domain> <host>Delete a glue recordporctl glue delete example.com ns1
ssl get <domain>Download the issued SSL bundleporctl ssl get example.com --out-dir ./certs
mcpRun the MCP server over stdioporctl 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 for jq and scripts.
porctl domain list -o json | jq -r '.[].domain'
porctl dns list example.com -t A -o json | jq '.[] | {name, content}'

Global flags

FlagDescription
--api-keyAPI key (env PORKBUN_API_KEY)
--secret-keySecret key (env PORKBUN_SECRET_KEY)
-o, --outputtable (default) or json
--timeoutRequest timeout (default 30s)
--ipv4Use the IPv4-only API host
--base-urlOverride 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)

ToolDescription
porkbun_pingVerify credentials and return the caller's public IP.
porkbun_pricing_getDefault domain pricing (registration, renewal, transfer) keyed by TLD.
porkbun_domain_listList all domains, with status, expiry, and settings.
porkbun_domain_getMetadata for one domain: status, expiry, auto-renew, WHOIS privacy, security lock, API access.
porkbun_domain_checkCheck whether a domain is available to register, with pricing.
porkbun_ns_getAuthoritative nameservers for a domain.
porkbun_dns_listList DNS records, optionally filtered by type and/or subdomain.
porkbun_dns_getA single DNS record by its numeric ID.
porkbun_dnssec_listRegistry DNSSEC (DS / key data) records for a domain.
porkbun_forward_listActive URL forwards, with destination, redirect type, path/wildcard settings.
porkbun_glue_listGlue records (host objects) with their IPv4/IPv6 addresses.
porkbun_ssl_retrieveThe 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-only mode to disable all mutations on the CLI, and a porctl account command to inspect your balance and top-up settings at a glance.

License

Released under the MIT License.

Ver o original no GitHub

Bom para

Relacionados