porkbun-mcp

Servidor MCP para dominios y DNS de Porkbun

GitHub

Documentación

porkbun-mcp

porkbun-mcp logo

Servidor MCP para dominios y DNS de Porkbun.

Úsalo desde cualquier cliente compatible con MCP para inspeccionar y gestionar:

dominios y servidores de nombres
registros DNS
DNSSEC
paquete de certificados SSL
redirección de URL

Diseñado para operaciones seguras:

comportamiento de solo lectura por defecto
las herramientas de mutación requieren modo de escritura explícito
las herramientas de escenarios por defecto usan dry_run: true

Por Qué Existe

Las operaciones de Porkbun suelen ser repetitivas y arriesgadas bajo presión de tiempo. Este proyecto expone las APIs de Porkbun como herramientas MCP para que los asistentes de IA puedan ejecutar flujos de trabajo de dominios de forma consistente y con salvaguardas.

Configuración en 3 Minutos

1) Requisitos previos

Node.js >=20
Credenciales de API de Porkbun:
- PORKBUN_API_KEY
- PORKBUN_SECRET_KEY
En el panel de Porkbun, el dominio objetivo debe estar marcado como accesible por API ("available via API"). Las claves a nivel de cuenta no son suficientes si el acceso API a nivel de dominio está deshabilitado.

Dónde obtener las claves:

Inicia sesión en Porkbun.
Abre la configuración de la cuenta y ve a API Access.
Genera/copia:
- PORKBUN_API_KEY (API Key)
- PORKBUN_SECRET_KEY (Secret API Key)
En la configuración del dominio, asegúrate de que el acceso API esté habilitado para cada dominio que quieras gestionar.

Instala las dependencias localmente (para desarrollo):

npm install
npm run build

2) Ejecución local rápida (stdio)

Modo de solo lectura:

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

Habilitar operaciones de escritura:

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

3) Verificar la configuración de CLI

node dist/index.js --help

Integraciones con Clientes MCP

El README de GitHub no admite pestañas nativas, por lo que esta sección usa bloques plegables tipo "pestaña". Si luego mueves la documentación a un sitio de documentación (Docusaurus/Nextra), puedes reutilizar los mismos fragmentos como pestañas reales.

Fragmento base del servidor (solo lectura 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"
    }
  }
}

Cursor

Añade un servidor MCP en la configuración de Cursor y pega el fragmento anterior como configuración del servidor. Si tu configuración espera un objeto externo, envuélvelo en:

{
  "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"
      }
    }
  }
}

Claude Desktop (macOS)

Actualiza ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "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"
      }
    }
  }
}

Otros clientes MCP (Windsurf, Cline, etc.)

La mayoría de los clientes usan la misma forma de mcpServers:

{
  "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 escritura con `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"
      }
    }
  }
}

Creación de dominio habilitada (peligroso)

{
  "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 (requisitos previos para el registro de dominios en la API de Porkbun):

Tu cuenta de Porkbun debe haber registrado al menos un dominio anteriormente (para cuentas nuevas, la primera compra puede necesitar hacerse a través de la interfaz web).
Tu dirección de correo electrónico y número de teléfono deben estar verificados.
Debes tener suficiente crédito en la cuenta (los registros por API se facturan desde el crédito de la cuenta).
cost debe proporcionarse en céntimos y debe coincidir con el valor devuelto por la verificación del dominio (duración mínima * precio).
Debes aceptar explícitamente los términos (agree_to_terms=true en este servidor, que se asigna a agreeToTerms="yes" para Porkbun).

Referencia:

Documentación de la API v3 de Porkbun (ver "Domain Create" y "Domain Check"): https://porkbun.com/api/json/v3/documentation

Primera Llamada Exitosa

Una vez configurado en tu cliente MCP, comienza con:

ping
pricing_get

Luego prueba un flujo de lectura:

dns_list para tu dominio

Antes de cualquier llamada de escritura, ejecuta primero una herramienta de escenario en modo dry_run.

Modelo de Seguridad

Las acciones de escritura están bloqueadas a menos que se establezca --get-muddy o PORKBUN_GET_MUDDY=true.
Las herramientas de escenarios están diseñadas para planificar antes de aplicar.
Las herramientas destructivas incluyen límites explícitos y confirmaciones.
Las credenciales de API son a nivel de cuenta. Los permisos de API a nivel de dominio en Porkbun siguen aplicándose.
El registro de dominios (domains_create) está deshabilitado por defecto. Requiere:
- modo de escritura (--get-muddy)
- indicador de habilitación explícito (--enable-domain-create o PORKBUN_ENABLE_DOMAIN_CREATE=true)
- dry_run=false + confirm_apply=true + agree_to_terms=true

Variables de Entorno

PORKBUN_API_KEY (obligatorio)
PORKBUN_SECRET_KEY (obligatorio)
PORKBUN_GET_MUDDY (opcional)
PORKBUN_ENABLE_DOMAIN_CREATE (opcional, peligroso)

Opciones de CLI

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

Qué Significa `--get-muddy`

--get-muddy habilita el modo de escritura.

Sin él, el servidor permanece en comportamiento seguro de solo lectura. Con él, se permiten herramientas de mutación (operaciones de crear/editar/eliminar/actualizar para DNS y configuración de dominios).

Usa este modo solo cuando:

estés listo para aplicar cambios reales de infraestructura
tu dominio esté habilitado por API en Porkbun
ya hayas validado el plan con llamadas de lectura o flujos de dry_run

Cobertura de Herramientas

Conectividad: ping, pricing_get
Dominios: listar, servidores de nombres, redirección de URL, registros glue (obtener/crear/actualizar/eliminar), disponibilidad
DNS: listar/obtener/crear/editar/eliminar (incluyendo por nombre/tipo)
DNSSEC: listar/crear/eliminar
SSL: obtención del paquete de certificados

Herramientas de escenarios:

dns_query
dns_upsert
domain_health_check
dns_remove
domain_redirect_ensure
domain_cutover_web
dns_batch_apply

Ayudantes para principiantes:

dns_audit
dns_setup
email_dns_setup
update_server_ip
subdomain_setup

Documentación detallada: docs/scenario-tools.md

Ejemplos Prácticos

dns_query por ID de registro:

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

dns_upsert modo de plan:

{
  "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 plan:

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

Notas de Seguridad

Nunca confirmes claves API reales en git.
Prefiere variables de entorno locales o un gestor de secretos.
Trata el modo de escritura como acceso de producción.

Desarrollo

npm install
npm run build

Ejecutar localmente:

npm run dev

Contribuciones

Las contribuciones son bienvenidas. Lee CONTRIBUTING.md antes de abrir un PR.

Licencia

MIT

porkbun-mcp

Documentación

porkbun-mcp

Por Qué Existe

Configuración en 3 Minutos

1) Requisitos previos

2) Ejecución local rápida (stdio)

3) Verificar la configuración de CLI

Integraciones con Clientes MCP

Fragmento base del servidor (solo lectura seguro)

Modo de escritura con npx

Creación de dominio habilitada (peligroso)

Primera Llamada Exitosa

Modelo de Seguridad

Variables de Entorno

Opciones de CLI

Qué Significa --get-muddy

Cobertura de Herramientas

Ejemplos Prácticos

Notas de Seguridad

Desarrollo

Contribuciones

Licencia

Modo de escritura con `npx`

Qué Significa `--get-muddy`