Porkbun MCP

🚀 porkbun-mcp

An MCP server for Porkbun domains and DNS, enabling inspection and management of various domain - related elements.

🚀 Quick Start

Prerequisites

• Node.js >=20
• Porkbun API credentials:
  • PORKBUN_API_KEY
  • PORKBUN_SECRET_KEY
• In the Porkbun panel, the target domain must be marked as API accessible ("available via API"). Account - level keys are not enough if domain - level API access is disabled.

Where to get the keys:

• Log in to Porkbun.
• Open account settings and go to API Access.
• Generate/copy:
  • PORKBUN_API_KEY (API Key)
  • PORKBUN_SECRET_KEY (Secret API Key)
• In the domain settings, ensure API access is enabled for each domain you want to manage.

Install dependencies locally (for development):

npm install
npm run build

Quick local run (stdio)

Read - only mode:

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

Enable write operations:

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

Verify CLI wiring

node dist/index.js --help

✨ Features

This project exposes Porkbun APIs as MCP tools, allowing AI assistants to execute domain workflows consistently and with guardrails. It can be used to inspect and manage:

• domains and nameservers
• DNS records
• DNSSEC
• SSL certificate bundle
• URL forwarding

It is built for safe operations:

• read - only behavior by default
• mutating tools require explicit write mode
• scenario tools default to dry_run: true

📦 Installation

Install dependencies locally (for development):

npm install
npm run build

💻 Usage Examples

Basic Usage

dns_query by record id:

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

Advanced Usage

dns_upsert plan mode:

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

📚 Documentation

MCP Client Integrations

GitHub README does not support native tabs, so this section uses collapsible "tab - like" blocks. If you later move docs to a docs site (Docusaurus/Nextra), you can reuse the same snippets as real tabs.

Base server snippet (safe read - only)

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

Write mode with 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"
      }
    }
  }
}

Domain create enabled (dangerous)

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

Important (Porkbun API domain registration prerequisites):

• Your Porkbun account must have registered at least one domain in the past (for new accounts, the first purchase may need to be done via the web UI).
• Your email address and phone number must be verified.
• You must have enough account credit (API registrations are billed from account credit).
• cost must be provided in pennies and must match the value returned by the domain check (minimum duration * price).
• You must explicitly accept terms (agree_to_terms=true in this server, which maps to agreeToTerms="yes" for Porkbun).

Reference:

• Porkbun API v3 docs (see "Domain Create" and "Domain Check"): https://porkbun.com/api/json/v3/documentation

First Successful Call

Once configured in your MCP client, start with:

• ping
• pricing_get

Then try one read flow:

• dns_list for your domain

Before any write call, run a scenario tool in dry_run mode first.

Safety Model

• Write actions are blocked unless --get-muddy or PORKBUN_GET_MUDDY=true is set.
• Scenario tools are designed to plan before apply.
• Destructive tools include explicit limits and confirmations.
• API credentials are account - level. Domain - level API permissions in Porkbun still apply.
• Domain registration (domains_create) is disabled by default. It requires:
  • write mode (--get-muddy)
  • explicit enable flag (--enable-domain-create or PORKBUN_ENABLE_DOMAIN_CREATE=true)
  • dry_run=false + confirm_apply=true + agree_to_terms=true

Environment Variables

• PORKBUN_API_KEY (required)
• PORKBUN_SECRET_KEY (required)
• PORKBUN_GET_MUDDY (optional)
• PORKBUN_ENABLE_DOMAIN_CREATE (optional, dangerous)

CLI Options

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

What --get-muddy Means

--get-muddy enables write mode.

Without it, the server stays in safe read - only behavior. With it, mutating tools are allowed (create/edit/delete/update operations for DNS and domain settings).

Use this mode only when:

• you are ready to apply real infrastructure changes
• your domain is API - enabled in Porkbun
• you have already validated the plan with read calls or dry_run flows

Tool Coverage

• Connectivity: ping, pricing_get
• Domains: list, nameservers, URL forwarding, glue records (get/create/update/delete), availability
• DNS: list/get/create/edit/delete (including by name/type)
• DNSSEC: list/create/delete
• SSL: certificate bundle retrieval

Scenario tools:

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

Beginner helpers:

• dns_audit
• dns_setup
• email_dns_setup
• update_server_ip
• subdomain_setup

Detailed docs:

Practical Examples

dns_query by record id:

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

dns_upsert plan mode:

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

Security Notes

• Never commit real API keys to git.
• Prefer local environment variables or a secret manager.
• Treat write mode as production access.

Development

npm install
npm run build

Run locally:

npm run dev

Contributing

Contributions are welcome. Read before opening a PR.

📄 License

MIT