porkbun-mcp

porkbun-mcp

Servidor MCP para domínios e DNS da Porkbun.

Use-o com qualquer cliente compatível com MCP para inspecionar e gerenciar:

• domínios e servidores de nomes
• registros DNS
• DNSSEC
• pacote de certificados SSL
• redirecionamento de URL

Construído para operações seguras:

• comportamento somente leitura por padrão
• ferramentas de mutação exigem modo de escrita explícito
• ferramentas de cenário padrão para dry_run: true

Por Que Isso Existe

As operações da Porkbun costumam ser repetitivas e arriscadas sob pressão de tempo. Este projeto expõe as APIs da Porkbun como ferramentas MCP para que assistentes de IA possam executar fluxos de trabalho de domínio de forma consistente e com proteções.

Configuração em 3 Minutos

1) Pré-requisitos

• Node.js >=20
• Credenciais da API da Porkbun:
  • PORKBUN_API_KEY
  • PORKBUN_SECRET_KEY
• No painel da Porkbun, o domínio de destino deve estar marcado como acessível via API ("available via API"). Chaves de nível de conta não são suficientes se o acesso à API de nível de domínio estiver desabilitado.

Onde obter as chaves:

• Faça login na Porkbun.
• Abra as configurações da conta e vá para API Access.
• Gere/copie:
  • PORKBUN_API_KEY (API Key)
  • PORKBUN_SECRET_KEY (Secret API Key)
• Nas configurações do domínio, garanta que o acesso à API esteja habilitado para cada domínio que você deseja gerenciar.

Instale as dependências localmente (para desenvolvimento):

npm install
npm run build

2) Execução local rápida (stdio)

Modo somente leitura:

PORKBUN_API_KEY=your_key \
PORKBUN_SECRET_KEY=your_secret \
node dist/index.js

Habilitar operações de escrita:

PORKBUN_API_KEY=your_key \
PORKBUN_SECRET_KEY=your_secret \
PORKBUN_GET_MUDDY=true \
node dist/index.js --get-muddy

3) Verificar a configuração da CLI

node dist/index.js --help

Integrações com Clientes MCP

O README do GitHub não suporta abas nativas, então esta seção usa blocos recolhíveis "semelhantes a abas". Se você mover a documentação para um site de docs (Docusaurus/Nextra) posteriormente, poderá reutilizar os mesmos trechos como abas reais.

Trecho base do servidor (somente leitura seguro)

{
  "porkbun-mcp": {
    "command": "npx",
    "args": ["-y", "porkbun-mcp"],
    "env": {
      "PORKBUN_API_KEY": "your_porkbun_api_key",
      "PORKBUN_SECRET_KEY": "your_porkbun_secret_api_key"
    }
  }
}

{
  "mcpServers": {
    "porkbun-mcp": {
      "command": "npx",
      "args": ["-y", "porkbun-mcp"],
      "env": {
        "PORKBUN_API_KEY": "your_porkbun_api_key",
        "PORKBUN_SECRET_KEY": "your_porkbun_secret_api_key"
      }
    }
  }
}

{
  "mcpServers": {
    "porkbun-mcp": {
      "command": "npx",
      "args": ["-y", "porkbun-mcp"],
      "env": {
        "PORKBUN_API_KEY": "your_porkbun_api_key",
        "PORKBUN_SECRET_KEY": "your_porkbun_secret_api_key"
      }
    }
  }
}

{
  "mcpServers": {
    "porkbun-mcp": {
      "command": "npx",
      "args": ["-y", "porkbun-mcp"],
      "env": {
        "PORKBUN_API_KEY": "your_porkbun_api_key",
        "PORKBUN_SECRET_KEY": "your_porkbun_secret_api_key"
      }
    }
  }
}

Modo de escrita com npx

{
  "mcpServers": {
    "porkbun-mcp": {
      "command": "npx",
      "args": ["-y", "porkbun-mcp", "--get-muddy"],
      "env": {
        "PORKBUN_API_KEY": "your_porkbun_api_key",
        "PORKBUN_SECRET_KEY": "your_porkbun_secret_api_key"
      }
    }
  }
}

Criação de domínio habilitada (perigoso)

{
  "mcpServers": {
    "porkbun-mcp": {
      "command": "npx",
      "args": ["-y", "porkbun-mcp", "--get-muddy", "--enable-domain-create"],
      "env": {
        "PORKBUN_API_KEY": "your_porkbun_api_key",
        "PORKBUN_SECRET_KEY": "your_porkbun_secret_api_key"
      }
    }
  }
}

Importante (pré-requisitos para registro de domínio na API da Porkbun):

• Sua conta Porkbun deve ter registrado pelo menos um domínio no passado (para contas novas, a primeira compra pode precisar ser feita pela interface web).
• Seu endereço de e-mail e número de telefone devem estar verificados.
• Você deve ter crédito suficiente na conta (registros via API são cobrados do crédito da conta).
• cost deve ser fornecido em centavos e deve corresponder ao valor retornado pela verificação de domínio (duração mínima * preço).
• Você deve aceitar explicitamente os termos (agree_to_terms=true neste servidor, que mapeia para agreeToTerms="yes" na Porkbun).

Referência:

• Documentação da API v3 da Porkbun (veja "Domain Create" e "Domain Check"): https://porkbun.com/api/json/v3/documentation

Primeira Chamada Bem-Sucedida

Depois de configurado no seu cliente MCP, comece com:

• ping
• pricing_get

Depois tente um fluxo de leitura:

• dns_list para o seu domínio

Antes de qualquer chamada de escrita, execute uma ferramenta de cenário no modo dry_run primeiro.

Modelo de Segurança

• Ações de escrita são bloqueadas a menos que --get-muddy ou PORKBUN_GET_MUDDY=true esteja definido.
• Ferramentas de cenário são projetadas para planejar antes de aplicar.
• Ferramentas destrutivas incluem limites e confirmações explícitos.
• As credenciais da API são de nível de conta. As permissões de API de nível de domínio na Porkbun ainda se aplicam.
• O registro de domínio (domains_create) está desabilitado por padrão. Ele exige:
  • modo de escrita (--get-muddy)
  • flag de habilitação explícita (--enable-domain-create ou PORKBUN_ENABLE_DOMAIN_CREATE=true)
  • dry_run=false + confirm_apply=true + agree_to_terms=true

Variáveis de Ambiente

• PORKBUN_API_KEY (obrigatório)
• PORKBUN_SECRET_KEY (obrigatório)
• PORKBUN_GET_MUDDY (opcional)
• PORKBUN_ENABLE_DOMAIN_CREATE (opcional, perigoso)

Opções de CLI

• --get-muddy
• --enable-domain-create (perigoso)
• --transport stdio
• --ipv4-only-api
• --help

O Que --get-muddy Significa

--get-muddy habilita o modo de escrita.

Sem ele, o servidor permanece em comportamento seguro somente leitura. Com ele, ferramentas de mutação são permitidas (operações de criar/editar/excluir/atualizar para DNS e configurações de domínio).

Use este modo apenas quando:

• você estiver pronto para aplicar mudanças reais de infraestrutura
• seu domínio estiver habilitado para API na Porkbun
• você já tiver validado o plano com chamadas de leitura ou fluxos de dry_run

Cobertura de Ferramentas

• Conectividade: ping, pricing_get
• Domínios: listar, servidores de nomes, redirecionamento de URL, registros glue (obter/criar/atualizar/excluir), disponibilidade
• DNS: listar/obter/criar/editar/excluir (inclusive por nome/tipo)
• DNSSEC: listar/criar/excluir
• SSL: recuperação do pacote de certificados

Ferramentas de cenário:

• dns_query
• dns_upsert
• domain_health_check
• dns_remove
• domain_redirect_ensure
• domain_cutover_web
• dns_batch_apply

Ajudantes para iniciantes:

• dns_audit
• dns_setup
• email_dns_setup
• update_server_ip
• subdomain_setup

Documentação detalhada: docs/scenario-tools.md

Exemplos Práticos

dns_query por ID de registro:

{
  "domain": "example.com",
  "selector": {
    "record_id": "123456789"
  }
}

dns_upsert modo de planejamento:

{
  "domain": "example.com",
  "match": {
    "type": "A",
    "subdomain": "www"
  },
  "target": {
    "content": "203.0.113.10",
    "ttl": 300
  },
  "dry_run": true
}

domains_check_bulk:

{
  "domains": ["example.com", "example.net", "example.org"],
  "concurrency": 1,
  "respect_limits": true,
  "delay_ms": 11000,
  "stop_on_rate_limit": true
}

dns_batch_apply plano:

{
  "domain": "example.com",
  "desired_records": [
    {
      "type": "A",
      "subdomain": "",
      "content": "198.51.100.42",
      "ttl": 300
    }
  ],
  "mode": "plan",
  "strategy": "merge",
  "max_changes": 5
}

Notas de Segurança

• Nunca envie chaves de API reais para o git.
• Prefira variáveis de ambiente locais ou um gerenciador de segredos.
• Trate o modo de escrita como acesso de produção.

Desenvolvimento

npm install
npm run build

Execute localmente:

npm run dev

Contribuindo

Contribuições são bem-vindas. Leia CONTRIBUTING.md antes de abrir um PR.

Licença

MIT