porkbun-mcp

MCP server for Porkbun domains and DNS.

Use it from any MCP-compatible client to inspect and manage:

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

Built for safe operations:

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

Why This Exists

Porkbun operations are often repetitive and risky under time pressure. This project exposes Porkbun APIs as MCP tools so AI assistants can execute domain workflows consistently and with guardrails.

3-Minute Setup

1) Prerequisites

• Node.js >=20
• Porkbun API credentials:
  • PORKBUN_API_KEY
  • PORKBUN_SECRET_KEY
• In 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

2) 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

3) Verify CLI wiring

node dist/index.js --help

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

<details> <summary><strong>Cursor</strong></summary>

Add an MCP server in Cursor settings and paste the snippet above as a server config. If your setup expects an outer object, wrap it into:

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

</details>

<details> <summary><strong>Claude Desktop (macOS)</strong></summary>

Update ~/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"
      }
    }
  }
}

</details>

<details> <summary><strong>Other MCP clients (Windsurf, Cline, etc.)</strong></summary>

Most clients use the same mcpServers shape:

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

</details>

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: docs/scenario-tools.md

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 CONTRIBUTING.md before opening a PR.

License

MIT