porkbun-mcp
# 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):
```bash
npm install
npm run build
```
### 2) Quick local run (stdio)
Read-only mode:
```bash
PORKBUN_API_KEY=your_key \
PORKBUN_SECRET_KEY=your_secret \
node dist/index.js
```
Enable write operations:
```bash
PORKBUN_API_KEY=your_key \
PORKBUN_SECRET_KEY=your_secret \
PORKBUN_GET_MUDDY=true \
node dist/index.js --get-muddy
```
### 3) Verify CLI wiring
```bash
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)
```json
{
"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:
```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>Claude Desktop (macOS)</strong></summary>
Update `~/Library/Application Support/Claude/claude_desktop_config.json`:
```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:
```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>
### Write mode with `npx`
```json
{
"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)
```json
{
"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`](docs/scenario-tools.md)
## Practical Examples
`dns_query` by record id:
```json
{
"domain": "example.com",
"selector": {
"record_id": "123456789"
}
}
```
`dns_upsert` plan mode:
```json
{
"domain": "example.com",
"match": {
"type": "A",
"subdomain": "www"
},
"target": {
"content": "203.0.113.10",
"ttl": 300
},
"dry_run": true
}
```
`domains_check_bulk`:
```json
{
"domains": ["example.com", "example.net", "example.org"],
"concurrency": 1,
"respect_limits": true,
"delay_ms": 11000,
"stop_on_rate_limit": true
}
```
`dns_batch_apply` plan:
```json
{
"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
```bash
npm install
npm run build
```
Run locally:
```bash
npm run dev
```
## Contributing
Contributions are welcome.
Read [`CONTRIBUTING.md`](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.
TDQS
Scored across 40 tools
Many tools have overlapping or indistinguishable purposes, especially dns_delete vs dns_remove vs dns_delete_by_name_type, dns_edit vs dns_edit_by_name_type, and dns_get vs dns_get_by_name_type. Setup/orchestration tools like dns_setup, subdomain_setup, email_dns_setup, domain_cutover_web, and update_server_ip are hard to distinguish without descriptions, and most tools lack descriptions entirely.
Most names use snake_case, which is readable, but conventions vary: some groups use plural resource prefixes (domains_list) while others use singular or bare verbs (dns_list, ssl_retrieve, ping). Verb choices are inconsistent across equivalent operations, such as delete vs remove and edit vs update, and several tools have no resource prefix at all.
At 40 tools, the surface is heavy for a Porkbun management server, and much of the count comes from near-duplicate variants like dns_delete and dns_delete_by_name_type. The broad domain/DNS feature set could justify many tools, but the current set appears bloated by redundant operations.
The tool surface covers a wide range of domain management workflows: domains, DNS records, DNSSEC, SSL retrieval, nameservers, URL forwarding, glue records, availability checks, pricing, and health/setup helpers. Minor gaps may exist around account-level or transfer operations, but the core lifecycle appears well covered.