# Porkbun MCP Server (official)

[![npm version](https://img.shields.io/npm/v/@porkbunllc/mcp-server.svg?color=cb3837&label=npm)](https://www.npmjs.com/package/@porkbunllc/mcp-server)
[![npm downloads](https://img.shields.io/npm/dm/@porkbunllc/mcp-server.svg)](https://www.npmjs.com/package/@porkbunllc/mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**The official MCP server from Porkbun, built and maintained by Porkbun** (by [Owen Borseth](https://github.com/oborseth), Porkbun's CTO). It is published on npm as [`@porkbunllc/mcp-server`](https://www.npmjs.com/package/@porkbunllc/mcp-server) and hosted by Porkbun at `https://mcp.porkbun.com/mcp`. Other "Porkbun MCP" projects on GitHub and in MCP directories are community wrappers around the public API; they are not made or supported by Porkbun. In the [official MCP Registry](https://registry.modelcontextprotocol.io) it is listed as **`com.porkbun/mcp`**, a name the registry grants only to whoever proves control of porkbun.com; community projects appear under `io.github.*` names.

A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes the [Porkbun v3 API](https://porkbun.com/api/json/v3/documentation) as native tools for AI agents — Claude Desktop, Cursor, Cline, and any other MCP-compatible client.

**Setup guide, client configs and the full tool list: [porkbun.com/mcp](https://porkbun.com/mcp)**

**No install: use the hosted connector.** Porkbun runs this server at `https://mcp.porkbun.com/mcp`. Add that URL as a custom connector in ChatGPT or Claude (or `claude mcp add --transport http porkbun https://mcp.porkbun.com/mcp` in Claude Code), sign in to Porkbun and approve. No API key to copy. Steps per client: [Connect ChatGPT or Claude](https://porkbun.com/llms/guides/connect-chatgpt-or-claude). How it is deployed: [`deploy/README.md`](deploy/README.md). The ChatGPT and Claude directory listings use a narrower variant, `/mcp/no-purchases` (no tool that spends money or returns a secret); it changes which tools are offered, not what a connection may do.

> **Status:** full Porkbun v3 coverage (domains, DNS, SSL, hosting, webhooks; current version on the npm badge above). Also runs **hosted** at `https://mcp.porkbun.com/mcp` for ChatGPT and Claude, with sign-in instead of API keys. Provisions **Cloud for WordPress** and mints WordPress REST API credentials so an agent can manage the site it just created. Moves domains to a customer's **own Cloudflare account** and then manages those records, the proxy and zone settings. An isolated **sandbox**: a `pk1_sb_` key runs every tool against a simulated environment with fake credit — no real registry actions, DNS changes or charges — and still delivers signed webhooks. A credential-free **mock server** returns schema-accurate example responses for any endpoint.

## What's included

**Read tools (free, no spend, no state changes)**

| Tool | Description |
|---|---|
| `ping` | Verify API connectivity and credentials |
| `check_domain` | Check availability and pricing for a single domain |
| `get_registration_requirements` | TLD registration requirements as JSON Schema — is it API-registerable, the create payload, and registry eligibility fields (.us nexus, .ca legal type, …) |
| `get_pricing` | Get registration/renewal/transfer pricing for all TLDs (no auth needed) |
| `list_marketplace` | Browse Porkbun Marketplace (names Porkbun customers list themselves); filter by TLD, max price, name substring. For every aftermarket at once, use `search_aftermarket` |
| `search_closeouts` | Search expired-domain closeouts; filter by age, price, TLD, name length; sort by registration date |
| `search_aftermarket` | Find taken names that are for sale (Afternic, Sedo, Atom, NameBright, DAX, Porkbun Marketplace), with price, sale type and a link to buy on porkbun.com |
| `get_closeout` | One closeout plus its binding total (closeout price + the renewal/transfer year) |
| `buy_closeout` | Buy a closeout outright. **Spends account credit** |
| `list_domains` | Paginate through domains; filter by tld, expiry, auto-renew, API access |
| `get_domain` | Get metadata for a single domain in the account |
| `get_balance` | Get account credit balance |
| `get_auto_topup` | Read auto top-up settings, whether a card is on file, and what a top-up would charge |
| `top_up_with_usdc` | Add credit with USDC on Base ($1-$500; Coinbase keeps ~1%, so use `INSUFFICIENT_FUNDS`'s `usdcAmountToCover`): returns an x402 URL an agent's wallet pays directly, and a payment page for the user |
| `get_usdc_topup_status` | Whether a USDC top-up has been paid and credited |
| `top_up_with_card_mpp` | A payment link an agent pays with the user's card over MPP (Stripe Link agent wallet); credit lands immediately |
| `send_phone_verification_code` | Texts (or calls) a code to the phone on the account, to clear `VERIFICATION_REQUIRED` |
| `confirm_phone_verification` | Verifies the phone with the code the user received |
| `send_email_verification_code` | Emails a code to the address on the account, to clear `VERIFICATION_REQUIRED` |
| `confirm_email_verification` | Verifies the email with the code from that email |
| `list_invoices` | The account's invoices, newest first: date, paid/refunded state, net total, domains, and a link to each on porkbun.com |
| `get_invoice` | One invoice as data: bill-to, payment method, lines with terms and expiry dates, and totals |
| `get_invoice_pdf` | The invoice PDF as an embedded file, plus a 15-minute download link that works without signing in |
| `get_api_settings` | The monthly limits actually enforced (`spendLimit` on purchases, `topupLimit` on credit added; $100 each by default), what was spent and added this month, alerts and auto top-up config |
| `get_nameservers` | Get current nameservers for a domain |
| `list_dns_records` | List DNS records for a domain |
| `scan_dns_records` | Discover what a domain publishes now, from its live nameservers (use before a transfer — a transfer carries no zone data) |
| `import_dns_records` | Bulk-create records from a supplied list or a live scan; idempotent, already-present records are skipped |
| `list_dnssec_records` | List DNSSEC DS records published at the registry |
| `list_url_forwards` | List URL forwarding rules for a domain (incl. exact `redirectType`: 301/302/307/masked) |
| `list_email_forwards` | List email forwards on a domain (address → mailbox), with limits and whether forwarding MX is in place |
| `list_mailboxes` | List email hosting mailboxes (including ones waiting to be set up), the price of another, and mail client settings |
| `list_glue_records` | List glue records (host-to-IP mappings) for a domain |
| `list_transfers` | List in-progress and recent inbound transfers |
| `get_transfer_status` | Get status of a specific inbound transfer |
| `get_ssl_bundle` | Retrieve the free Porkbun-issued SSL bundle for a domain |
| `get_contacts` | Get a domain's four contacts (registrant/admin/tech/billing) with current values |
| `get_webhook_event_types` | List the event types a webhook endpoint can subscribe to |
| `list_webhooks` | List webhook endpoints (URL, events, status, delivery health, secret) |
| `get_webhook` | Get a single webhook endpoint by id |
| `list_webhook_deliveries` | List recent delivery attempts (status, attempts, HTTP, error); ~30-day history |
| `get_webhook_delivery` | Get a single delivery incl. the full signed payload |
| `list_doc_topics` | List Porkbun API doc topics (the docs index) |
| `read_doc` | Read a doc page as Markdown (`dns`, `webhooks`, … or `overview`/`full`) |
| `search_docs` | Keyword-search the full reference; returns the most relevant sections |

The `list_doc_topics` / `read_doc` / `search_docs` tools let an agent ground itself in Porkbun's own documentation (the `/llms` Markdown surface) mid-conversation — no web browsing required, and **no API credentials needed**. You can add the server purely to research the API, then supply keys when you're ready for live operations.

**Account funding (charges a saved card, not credit)**

| Tool | What it does |
|------|--------------|
| `configure_auto_topup` | Turn auto top-up on/off: below `threshold_cents`, add `amount_cents` from the saved payment method. Amounts set via the API are capped at $500 |
| `top_up_account_credit` | **Charges the saved card now** and adds the credit. Omit `amount_cents` for the account's configured amount (or $50 if never set), or pass `amount_cents` (500-50000) for a one-off figure. Ask the user first, in dollars. 5/day, 20/month, within the monthly spend limit |

**Domain lifecycle writes (spend account credit)**

| Tool | Description |
|---|---|
| `register_domain` | Register a new domain — call `check_domain` first to confirm price. Pays from credit, directly in USDC (`pay_with_usdc`), or by card with a hold (`pay_with_card`) |
| `renew_domain` | Renew an existing domain |
| `transfer_domain` | Initiate an inbound transfer (returns transferId; takes 5-7 days) |
| `get_transfer_setup` | Where a held inbound transfer is and what it is waiting on |
| `prepare_transfer` | Create the DNS zone for a held transfer, before the domain moves |
| `start_transfer` | Release a held transfer to the registry (refuses on an empty zone) |
| `cancel_transfer` | Cancel a pending inbound transfer and refund it |
| `update_transfer_auth_code` | Replace the auth code on a stalled transfer and re-queue it |

**Domain settings writes (free)**

| Tool | Description |
|---|---|
| `update_auto_renew` | Turn auto-renewal on or off |
| `update_nameservers` | Replace the nameserver list for a domain (full replace, not append) |
| `update_contacts` | Edit domain contacts — any subset of registrant/admin/tech/billing; a registrant change fires the new-owner notice email. On address-validated TLDs (`.de`/`.nrw`/`.uk`/`.us`/`.ca`/`.au`/`.eu`/`.in`/`.nz` families) it validates the registrant address — resolve with `address_validation_choice`. A `.au` registrant name/org change is a website-only ownership trade. |

**DNS / DNSSEC / URL- and email-forwarding / glue writes (free)**

| Tool | Description |
|---|---|
| `create_dns_record` | Create a new DNS record (A, AAAA, CNAME, MX, TXT, etc.) |
| `update_dns_record` | Update an existing DNS record by its ID |
| `delete_dns_record` | Delete a DNS record by its ID |
| `create_dnssec_record` | Submit a DNSSEC DS record to the registry |
| `delete_dnssec_record` | Remove a DNSSEC DS record by key tag |
| `create_url_forward` | Create a URL forwarding rule (permanent/temporary/masked; optional `redirect_type` 301/302/307/masked) |
| `delete_url_forward` | Delete a URL forwarding rule by ID |
| `create_email_forward` | Forward an address at the domain to another mailbox; asks first (`DNS_CHANGE_CONFIRMATION_REQUIRED`) before replacing another mail service's MX or rewriting SPF |
| `delete_email_forward` | Delete an email forward; the last one also removes the forwarding MX/SPF |
| `setup_mailbox` | Set up a waiting email hosting mailbox (paid, or the free trial every registration includes); generates the password unless one is given |
| `set_email_password` | Change a mailbox's password |
| `create_glue_record` | Create a glue record (host-to-IP mapping at the registry) |
| `update_glue_record` | Replace the IP list for a glue record |
| `delete_glue_record` | Delete a glue record by host |

**Secure Static Hosting**

| Tool | Description |
|---|---|
| `list_hosting_plans` | List API-provisionable hosting products + plans, with price (cents), interval, trial length, features |
| `create_hosting` | Provision hosting for a domain by `sku` (from `list_hosting_plans`) — first provision per domain is a 15-day free trial that auto-renews at the plan price; re-provision after deprovision is charged to account credit (one free trial per domain). Switches the domain to Porkbun NS (gated by `agree_to_nameserver_change`); requires `acknowledged_cost`. `dry_run` supported |
| `create_mailbox` | Buy an email hosting mailbox ($36/yr, renews yearly) and set it up in one call; `cost_cents` must match, `dry_run` quotes; paid from credit or with `pay_with_card` / `pay_with_usdc` |
| `renew_mailbox` | Add a year to a mailbox now at its `renewalPrice` (set-up mailboxes also auto-renew); paid from credit or with `pay_with_card` / `pay_with_usdc` |
| `get_hosting` | Get hosting status for a domain (plan, trial, expiry, auto-renew) |
| `deploy_site` | Upload static files (base64, ≤10MB/call) to a domain's hosting |
| `list_hosting_files` | List files under a path in a domain's hosting |
| `delete_hosting_file` | Delete a file (or empty dir) from a domain's hosting |
| `make_hosting_dir` | Create a directory (and missing parents) in a domain's hosting (deploy auto-creates dirs in a file path) |
| `delete_hosting` | Deprovision (cancel) hosting for a domain |

**Cloud for WordPress**

`create_hosting` with a `CLOUDWORDPRESS…` sku provisions a managed WordPress site instead of static hosting (the file tools don't apply — manage it through WordPress).

| Tool | Description |
|---|---|
| `create_wp_credentials` | Mint a WordPress **Application Password** (returned once) so an agent can drive the site via `/wp-json/` with HTTP Basic. Defaults to a dedicated least-privilege `editor` user; `administrator` requires an explicit acknowledgement (it can install plugins = run code) |
| `list_wp_credentials` | List application passwords on the site (metadata only — passwords can't be re-read) |
| `delete_wp_credentials` | Revoke an application password by uuid, or all of them |

**Cloudflare connect** (move domains to the customer's own Cloudflare account)

Connecting the Cloudflare account itself is a **human** step — Cloudflare's consent screen has to be completed in a browser — so `get_cloudflare_connection` hands you a URL to show your user, then acts as the poll target. Everything after that is automated.

- `get_cloudflare_connection` — connected or not, and where to send the human if not (poll this)
- `list_cloudflare_inventory` — every domain with its eligibility and a plain-English reason
- `preview_cloudflare_move` — exactly which records a move would copy or drop, queueing nothing
- `connect_domains_to_cloudflare` — queue one or many (async: returns *queued*, never *connected*)
- `get_cloudflare_queue` / `get_cloudflare_domain_status` — progress, and the audit trail
- `retry_cloudflare_domain` / `rollback_cloudflare_domain` — re-queue a failure, or restore Porkbun nameservers
- `get_cloudflare_records` / `create_cloudflare_record` / `edit_cloudflare_record` / `delete_cloudflare_record` — manage DNS in the zone that actually answers once a domain has moved
- `set_cloudflare_proxy` — turn the orange cloud on or off, per record (a move always imports DNS-only, on purpose)
- `get_cloudflare_zone` — Cloudflare's own zone state, plus nameserver-drift detection
- `get_cloudflare_zone_settings` / `set_cloudflare_zone_settings` — SSL mode and friends
- `disconnect_cloudflare` — forget the grant (domains already moved keep working)

**Sandbox / test mode**

Use a **sandbox API key** (public key prefixed `pk1_sb_`, secret `sk1_sb_`) and *every* tool above runs against an isolated test environment — same server, you just swap the key. Registrations, renewals, transfers, DNS, contacts, glue, and DNSSEC are all simulated against a separate sandbox datastore: **no real registry actions, no DNS changes, no certificates, and no charges**. Your sandbox account starts with fake account credit, availability/pricing reflect the real catalog, and every response includes `"sandbox": true`. Create a sandbox key on [porkbun.com/account/api](https://porkbun.com/account/api). Or mint one instantly with **`create_sandbox_key`** — no signup, no credentials. (Hosting and email endpoints aren't simulated and return `SANDBOX_UNSUPPORTED` with a sandbox key.)

| Tool | Description |
|---|---|
| `request_api_key` | Start creating a live API key the account holder approves in the browser (optionally with only some permissions); returns the approval link |
| `retrieve_api_key` | After approval, collect the new key pair once |
| `create_sandbox_key` | **No credentials needed** — instantly mint a throwaway sandbox key pair (`pk1_sb_`/`sk1_sb_`, $1000 fake credit) so an agent can start testing before it has any keys |
| `sandbox_topup` | Sandbox only — grant fake account credit (default $1000) so paid ops can keep being exercised after funds run out |
| `sandbox_reset` | Sandbox only — wipe the sandbox account's domains/DNS/orders/credit and re-grant $1000, for a clean slate between test runs |
| `sandbox_trigger_webhook` | Sandbox only — fire a sample signed webhook event of any type (incl. cron-driven `domain.expiring`) to your registered endpoints, to test your handler + signature verification on demand |

**Mock server (no credentials)**

`mock_call` returns a schema-accurate example response for any endpoint with **no key required** — nothing to set up. Pass a `path` like `domain/listAll` or `dns/create/example.com` (omit it to list every mockable endpoint), or set `error: true` for the error shape. Responses touch no datastore and match the live API's shape exactly, so you can build and test client code before you have any credentials.

| Tool | Description |
|---|---|
| `mock_call` | **No credentials needed** — schema-accurate example response for any endpoint (`path` mirrors the real route; `error: true` for the error shape; omit `path` to list all mockable endpoints) |

**Webhook writes (free)**

| Tool | Description |
|---|---|
| `create_webhook` | Register an HTTPS endpoint to receive signed event payloads; returns the signing secret |
| `update_webhook` | Change an endpoint's URL, events, or status (ACTIVE/DISABLED) |
| `rotate_webhook_secret` | Generate a new signing secret for an endpoint |
| `test_webhook` | Send a `webhook.test` event to confirm reachability and signature verification |
| `resend_webhook` | Re-queue a past delivery (reuses the original event id) |
| `delete_webhook` | Delete a webhook endpoint |

Porkbun POSTs a signed JSON payload to your endpoint when subscribed events occur (`domain.registered`, `domain.renewed`, `domain.transfer.completed`, `domain.expiring`, `dns.record.created|updated|deleted`, `cloudflare.connect.completed|failed`, `account.verification.code_sent|completed`; fields per event: https://porkbun.com/llms/webhooks). Verify the `X-Porkbun-Signature` header — it's `sha256=` + HMAC-SHA256 of `{timestamp}.{rawBody}` keyed by the endpoint secret, where `{timestamp}` is the `X-Porkbun-Webhook-Timestamp` header.

## Claude plugin

[`plugin/`](plugin/) is a Claude plugin (claude.ai, Cowork and Claude Code): the
hosted connector at `https://mcp.porkbun.com/mcp/no-purchases` plus four skills:
`publish-website` (publish a site Claude builds to Porkbun Secure Static
Hosting instead of giving upload steps), `change-dns-safely`, `diagnose-domain`
(site down, mail bouncing, DNS not updating) and `move-dns-to-porkbun`. It holds no
code. Install it in Claude Code with `/plugin marketplace add oborseth/Porkbun-MCP`
then `/plugin install porkbun@porkbun` (the repo root carries a marketplace file,
`.claude-plugin/marketplace.json`, pointing at `./plugin`), or try a working copy
with `claude --plugin-dir ./plugin`. Raise `version`
in `plugin/.claude-plugin/plugin.json` with every change to the folder.

## Gemini CLI

```
gemini extensions install https://github.com/oborseth/Porkbun-MCP
```

Adds the hosted server (`gemini-extension.json` at the repo root) and a short
`GEMINI.md` with usage rules. Then run `/mcp auth porkbun` to sign in with your
Porkbun account. Keep `version` in `gemini-extension.json` in step with
`package.json`: the extension gallery picks up tagged releases.

## Install

You'll need [Node.js](https://nodejs.org) 18 or newer.

```bash
npx -y @porkbunllc/mcp-server
```

This downloads and runs the latest version on demand. No global install needed.

## Configure your MCP client

### Claude Desktop

Add this to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "porkbun": {
      "command": "npx",
      "args": ["-y", "@porkbunllc/mcp-server"],
      "env": {
        "PORKBUN_API_KEY": "pk1_your_public_key_here",
        "PORKBUN_SECRET_API_KEY": "sk1_your_secret_key_here"
      }
    }
  }
}
```

Restart Claude Desktop. Porkbun tools should appear in the tool picker.

> **Docs-only, no keys:** the documentation tools (`search_docs`, `read_doc`, `list_doc_topics`) work without credentials, so you can omit the `env` block entirely to use the server just for API research. The authenticated tools return a clear "set PORKBUN_API_KEY" message until you add keys.

### Cursor / Cline / Continue

**Cursor, one click:** [Add Porkbun to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=porkbun&config=eyJ1cmwiOiJodHRwczovL21jcC5wb3JrYnVuLmNvbS9tY3AifQ==) adds the hosted server (`https://mcp.porkbun.com/mcp`); you sign in with Porkbun on first use, no API key. If the link doesn't open from here (some sites strip `cursor://` links), use the button on https://porkbun.com/mcp.

For the local server, most MCP-aware editors use the same `mcpServers` config block as above. See your client's documentation for the exact location. Agents installing it can follow [llms-install.md](llms-install.md).

## Get API keys

Create API keys at [porkbun.com/account/api](https://porkbun.com/account/api). You'll need both the public key (`pk1_…`) and the secret key (`sk1_…`).

Or let the assistant get one: the server starts without keys, and `request_api_key` (no credentials needed) returns a link where you approve a new key, optionally with only some permissions; `retrieve_api_key` then hands the assistant the key pair once. Put it in the config below and restart the server.

By default, API access is opt-in per domain. To use the API to manage all your domains, enable the "Opt In All Domains" toggle in the same settings page. Otherwise you'll need to enable API access for each domain individually under Domain Management.

### Recommended: scope the key to your agent

Each API key supports three optional restrictions, set at [porkbun.com/account/api](https://porkbun.com/account/api) when you create the key, or later with the gear icon next to it:

- **Allowed IPs** — one entry per line; supports bare IPv4/IPv6 plus CIDR ranges (`198.51.100.0/24`, `2001:db8::/32`). Requests from other IPs fail with HTTP 403 `IP_NOT_ALLOWED` before any other check runs.
- **Allowed domains** — one entry per line, exact match. Operations against domains not in the list fail with HTTP 403 `DOMAIN_NOT_ALLOWED`.
- **Permissions** — Full access, **Read-only**, **Manage, but no purchases**, or custom scopes (`read`, `dns`, `domains`, `email`, `hosting`, `purchase`, `funding`, `account`). A tool call outside them fails with HTTP 403 `INSUFFICIENT_SCOPE` and changes nothing; `ping` shows the key's `scopes`.

Empty fields = no restriction (matches current behavior). When you give an MCP server a key, the recommended pattern is:

1. Create a fresh key dedicated to the agent (not your master key).
2. List the specific domains the agent should manage.
3. Give it only the permissions it needs (often **Manage, but no purchases**).
4. If you know the agent's egress IP, list it too.

The blast radius of an accidentally-leaked key drops to "operations on these domains from this IP" instead of "anything on the account."

## Environment variables

| Variable | Required | Purpose |
|---|---|---|
| `PORKBUN_API_KEY` | for live ops | Your Porkbun public API key. Omit to use only the credential-free tools (documentation, `create_sandbox_key`, `request_api_key` / `retrieve_api_key`). |
| `PORKBUN_SECRET_API_KEY` | for live ops | Your Porkbun secret API key. Omit to use only the credential-free tools (documentation, `create_sandbox_key`, `request_api_key` / `retrieve_api_key`). |
| `PORKBUN_BASE_URL` | no | Override the API base URL (e.g. for testing against `api-betamax.porkbun.com/api/json/v3`) |
| `PORKBUN_DOCS_BASE` | no | Override the docs host used by the `*_doc(s)` tools (default `https://porkbun.com`) |
| `PORKBUN_X402_PRIVATE_KEY` | no | Private key (`0x…`) of a Base wallet holding USDC. Lets the purchase tools pay directly with `pay_with_usdc: true` in one call. Use a wallet holding only what you are willing to spend. |
| `PORKBUN_X402_MAX_CENTS` | no | Largest single USDC payment the server will sign, in cents (default `5000`, $50). |

## Local development

```bash
git clone https://github.com/oborseth/Porkbun-MCP.git
cd Porkbun-MCP
npm install
npm run build
npm start          # or: node dist/index.js
```

The server speaks JSON-RPC 2.0 over stdio. Smoke test from a shell:

```bash
(printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}') \
  | PORKBUN_API_KEY=pk1_… PORKBUN_SECRET_API_KEY=sk1_… node dist/index.js
```

## Paying for purchases directly in USDC (x402)

`register_domain`, `renew_domain`, `transfer_domain`, `buy_closeout`, `create_hosting`, `create_mailbox` and `renew_mailbox` take `pay_with_usdc: true`, which skips account credit entirely. The API answers with an x402 payment requirement (USDC on Base, the exact price), and:

- **with `PORKBUN_X402_PRIVATE_KEY` set**, this server signs it and the purchase completes in the same tool call. It only signs terms that are exactly the quoted price in USDC on Base, and never above `PORKBUN_X402_MAX_CENTS`;
- **without it** (and always on the hosted connector, which holds no one's key), the tool returns `status: PAYMENT_REQUIRED` with a `checkoutId`, an `x402Url` and a `payUrl`. Pay the `x402Url` with a wallet tool (for example Coinbase's `awal x402 pay <x402Url> --scheme auth-capture`) or have the user pay the `payUrl` page, then call the same tool again with `usdc_checkout_id`.

If a purchase fails after payment, the payment is not sent back to the wallet: it stays on the Porkbun account as credit (the error says so, with the new balance), ready to retry from credit or spend on anything else. Guide: [Pay with USDC (x402)](https://porkbun.com/llms/guides/pay-with-usdc-x402).

## Paying for purchases by card, with a hold (Stripe MPP)

The same five tools take `pay_with_card: true` for a user with a Stripe Link agent wallet. The tool returns `status: PAYMENT_REQUIRED` with a single-use `payUrl` and a `cardPaymentId`; pay the link with an MPP wallet tool (`link-cli mpp pay <payUrl> -X POST --context "..."`; the user approves in Link), which only **authorizes** the card. Call the same tool again with `card_payment_id`: the card is charged if the purchase succeeds, and the hold is released (nothing charged) if it fails. Guide: [Pay with the user's card (MPP)](https://porkbun.com/llms/guides/pay-with-card-mpp).

## Money parameters are in cents, and say so

Every money parameter ends in `_cents` and takes integer US cents: `cost_cents: 1108` is $11.08, `amount_cents: 803` is $8.03. The unit is in the name because some clients build their approval prompt from the raw arguments, and a bare `amount: 803` was shown to a user as "$803". The old names (`cost`, `amount`, `threshold`, `acknowledged_cost`, `price_min`, `price_max`) are still accepted in the same unit; sending both names with different values is refused before anything reaches the API.

## Reliability

Write operations automatically attach a per-call `Idempotency-Key` header. Retried calls within 24 hours return the cached response, so your agent can safely retry on network errors without double-charging or double-registering.

## Privacy

This MCP server is a thin client that runs **locally** (on your machine, or wherever you host it) and relays your requests directly to the Porkbun API over HTTPS. It does not add any data collection of its own:

- **What it sends, and to whom.** Your API key/secret and the arguments of each tool call are sent only to `https://api.porkbun.com` (and, for the credential-free documentation and mock tools, to `https://porkbun.com`). Nothing is sent anywhere else.
- **Storage.** The server keeps your credentials in memory for the lifetime of the process (read from environment variables); it does not write them to disk, log them, or cache your data.
- **Hosted connector.** At `mcp.porkbun.com` the same code runs on Porkbun's infrastructure. It holds no API keys: each request carries the user's OAuth access token, which is forwarded to the Porkbun API and kept in memory only briefly (a 30-second validity cache). Request logs record method, path, status and timing, never tokens or request bodies.
- **No telemetry.** There is no analytics, tracking, or third-party sharing performed by this connector.
- **Data you access through it** (domains, DNS, contacts, billing, etc.) is your Porkbun account data, handled by Porkbun under its policy.

Full data-handling, retention, third-party, and contact details are in Porkbun's privacy policy: **https://porkbun.com/legal/agreement/privacy_policy**

## License

MIT

## Links

- [Setup guide and tool list](https://porkbun.com/mcp)
- [Porkbun API documentation](https://porkbun.com/api/json/v3/documentation)
- [Privacy policy](https://porkbun.com/legal/agreement/privacy_policy)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [Issues / contributions](https://github.com/oborseth/Porkbun-MCP/issues)