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.

Related MCP server: porkbun-mcp-server

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

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

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

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

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

Strict tool arguments and registration cost

All tools reject undeclared arguments. Calls that previously ignored extra fields now fail validation before contacting Porkbun. For dns_get_by_name_type, dns_edit_by_name_type, and dns_delete_by_name_type, use subdomain, not name. Omit it or pass an empty string to target the zone apex. dns_create and dns_edit use name.

domains_create.cost is an integer in US cents matching the current quote. The default dry_run: true only returns a local plan and does not check availability or price with Porkbun. Execution requires dry_run: false, confirm_apply: true, agree_to_terms: true, write mode and domain-create enablement.

Run npm test for MCP regression checks with mocked HTTP and no real purchases.

Card payment (0.4.0)

Use pay_with: "card" on domains_create. Before a live call, generate and save idempotency_key (16–128 ASCII letters, digits, underscores or hyphens; UUIDs work). The caller must retain the exact request and key across restarts. No durable server ledger or automatic key generation is provided. Dry-run stays local and defaults to true. Existing write, registration, terms and confirmation gates still apply.

A 402 returns a flat PAYMENT_REQUIRED result with payUrl, cardPaymentId and expiresAt. The account holder approves the exact purchase in an external MPP wallet. This server never pays links or switches to credit. Treat the URL and payment id as sensitive and avoid sharing histories containing them.

After authorization, repeat the purchase with card_payment_id, explicit card mode and a NEW saved key because the body changed. Identical retries, including after lost responses, use the original key. Porkbun documents a 24-hour replay window; reconcile older or uncertain requests before attempting another purchase.

Timeouts and malformed responses report unknown outcome, never an invented no-charge result. Card responses use an allowlist; raw messages, arbitrary fields and card details are omitted. Only explicit payment booleans are retained on API errors. Responses are capped at 64 KiB, redirects refused, and payment URLs restricted to HTTPS on porkbun.com under /pay/, without credentials, query or fragment. Unsupported shapes fail closed. Existing credit calls retain their response wrapper.

Official contract: https://porkbun.com/llms/guides/pay-with-card-mpp Validation uses mocked HTTP only; no live payments were made.