@porkbunllc/mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Porkbun, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# Porkbun MCP Server
+
+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.
+
+> **Status:** v0.1 — read-only tools only. Write operations (register, DNS edits, SSL provisioning) coming in subsequent releases.
+
+## What's included (v0.1)
+
+| Tool | Description |
+|---|---|
+| `ping` | Verify API connectivity and credentials |
+| `check_domain` | Check availability and pricing for a single domain |
+| `list_domains` | Paginate through domains in the authenticated account |
+| `get_balance` | Get account credit balance |
+| `get_pricing` | Get registration/renewal/transfer pricing for all TLDs |
+| `list_dns_records` | List DNS records for a domain |
+| `get_ssl_bundle` | Retrieve the free Porkbun-issued SSL bundle for a domain |
+
+## 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.
+
+### Cursor / Cline / Continue
+
+Most MCP-aware editors use a similar `mcpServers` config block. See your client's documentation for the exact location.
+
+## 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_…`).
+
+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.
+
+## Environment variables
+
+| Variable | Required | Purpose |
+|---|---|---|
+| `PORKBUN_API_KEY` | yes | Your Porkbun public API key |
+| `PORKBUN_SECRET_API_KEY` | yes | Your Porkbun secret API key |
+| `PORKBUN_BASE_URL` | no | Override the API base URL (e.g. for testing against `api-betamax.porkbun.com/api/json/v3`) |
+
+## 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
+```
+
+## Reliability
+
+All write operations (when added in future releases) will automatically attach a per-call `Idempotency-Key` header. Retried calls within 24 hours return the cached response — your agent can safely retry on network errors without double-charging.
+
+## License
+
+MIT
+
+## Links
+
+- [Porkbun API documentation](https://porkbun.com/api/json/v3/documentation)
+- [Model Context Protocol](https://modelcontextprotocol.io)
+- [Issues / contributions](https://github.com/oborseth/Porkbun-MCP/issues)

package/dist/api.js

@@ -0,0 +1,58 @@
+import { randomUUID } from "node:crypto";
+const DEFAULT_BASE_URL = "https://api.porkbun.com/api/json/v3";
+export function loadConfig() {
+    const apiKey = process.env.PORKBUN_API_KEY?.trim() ?? "";
+    const secretApiKey = process.env.PORKBUN_SECRET_API_KEY?.trim() ?? "";
+    const baseUrl = (process.env.PORKBUN_BASE_URL?.trim() || DEFAULT_BASE_URL).replace(/\/$/, "");
+    const userAgent = `porkbun-mcp/${process.env.npm_package_version ?? "0.1.0"}`;
+    if (!apiKey || !secretApiKey) {
+        throw new Error("Missing credentials. Set PORKBUN_API_KEY and PORKBUN_SECRET_API_KEY environment variables. " +
+            "Create keys at https://porkbun.com/account/api");
+    }
+    return { apiKey, secretApiKey, baseUrl, userAgent };
+}
+/**
+ * Call a Porkbun v3 API endpoint. The path is relative to the base URL and
+ * should start with a slash (e.g. `/domain/listAll`). Auth is injected
+ * automatically: header-based for GET, body-based for POST.
+ */
+export async function call(config, path, opts = {}) {
+    const method = opts.method ?? "POST";
+    const url = `${config.baseUrl}${path.startsWith("/") ? path : `/${path}`}`;
+    const headers = {
+        "User-Agent": config.userAgent,
+        Accept: "application/json",
+    };
+    let body;
+    if (method === "GET") {
+        headers["X-API-Key"] = config.apiKey;
+        headers["X-Secret-API-Key"] = config.secretApiKey;
+    }
+    else {
+        headers["Content-Type"] = "application/json";
+        body = JSON.stringify({
+            ...(opts.body ?? {}),
+            apikey: config.apiKey,
+            secretapikey: config.secretApiKey,
+        });
+        if (opts.idempotent) {
+            headers["Idempotency-Key"] = randomUUID();
+        }
+    }
+    const res = await fetch(url, { method, headers, body });
+    const text = await res.text();
+    let parsed;
+    try {
+        parsed = text ? JSON.parse(text) : {};
+    }
+    catch {
+        throw new Error(`Porkbun API returned non-JSON response (HTTP ${res.status}): ${text.slice(0, 300)}`);
+    }
+    const data = parsed;
+    if (!res.ok || data.status === "ERROR") {
+        const code = data.code ? ` [${data.code}]` : "";
+        const msg = data.message ?? `HTTP ${res.status}`;
+        throw new Error(`Porkbun API error${code}: ${msg}`);
+    }
+    return parsed;
+}

package/dist/index.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./api.js";
+import { tools } from "./tools.js";
+const server = new McpServer({
+    name: "porkbun-mcp",
+    version: "0.1.0",
+});
+// Defer config loading until the first tool call. tools/list works without
+// credentials so MCP clients can still discover what's available.
+let cachedConfig = null;
+function getConfig() {
+    if (!cachedConfig)
+        cachedConfig = loadConfig();
+    return cachedConfig;
+}
+for (const tool of tools) {
+    server.registerTool(tool.name, {
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+    }, async (args) => {
+        try {
+            const result = await tool.handler(getConfig(), args);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(result, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                isError: true,
+                content: [{ type: "text", text: message }],
+            };
+        }
+    });
+}
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Errors during transport are already logged by the SDK.
+}
+main().catch((err) => {
+    console.error("Fatal:", err);
+    process.exit(1);
+});

package/dist/tools.js

@@ -0,0 +1,104 @@
+import { z } from "zod";
+import { call } from "./api.js";
+const ping = {
+    name: "ping",
+    description: "Verify the Porkbun API connection and credentials. Returns the caller's public IP and whether the API key is valid. Use this as a first sanity check before making other calls.",
+    inputSchema: {},
+    handler: async (config) => {
+        return await call(config, "/ping", { method: "POST" });
+    },
+};
+const check_domain = {
+    name: "check_domain",
+    description: "Check whether a single domain is available for registration and what it costs. Returns availability, registration price, renewal price, transfer price, and (for premium domains) extended pricing details. Pricing is in USD. Use this BEFORE register_domain to confirm cost — Porkbun rejects registrations whose `cost` doesn't match the current quote.",
+    inputSchema: {
+        domain: z
+            .string()
+            .min(3)
+            .describe("Fully qualified domain name to check, e.g. `example.com`"),
+    },
+    handler: async (config, args) => {
+        const domain = String(args.domain).toLowerCase();
+        return await call(config, `/domain/checkSingleDomain/${encodeURIComponent(domain)}`, {
+            method: "GET",
+        });
+    },
+};
+const list_domains = {
+    name: "list_domains",
+    description: "List domains in the authenticated Porkbun account. Returns one page of domains with metadata (expire date, auto-renew status, lock status, whois privacy status). Supports pagination with `start`. Use `includeLabels` to also return user-defined labels.",
+    inputSchema: {
+        start: z
+            .number()
+            .int()
+            .min(0)
+            .optional()
+            .describe("Pagination offset. Defaults to 0. Each page returns up to 1000 domains."),
+        includeLabels: z
+            .boolean()
+            .optional()
+            .describe("If true, include user-defined domain labels in the response."),
+    },
+    handler: async (config, args) => {
+        const params = new URLSearchParams();
+        if (args.start !== undefined)
+            params.set("start", String(args.start));
+        if (args.includeLabels)
+            params.set("includeLabels", "yes");
+        const qs = params.toString() ? `?${params.toString()}` : "";
+        return await call(config, `/domain/listAll${qs}`, { method: "GET" });
+    },
+};
+const get_balance = {
+    name: "get_balance",
+    description: "Get the available account credit balance for the authenticated Porkbun account. Returns the balance in cents (integer) and a human-readable display string (e.g. `$12.34`). Use this to check spend headroom before initiating registrations or renewals.",
+    inputSchema: {},
+    handler: async (config) => {
+        return await call(config, "/account/balance", { method: "GET" });
+    },
+};
+const get_pricing = {
+    name: "get_pricing",
+    description: "Get current Porkbun pricing for all supported TLDs. Returns registration, renewal, and transfer prices per TLD in USD. No authentication required. Useful when an agent needs to compare TLD costs before registering. Note: this returns standard pricing only — premium domains have their own per-domain pricing reported by check_domain.",
+    inputSchema: {},
+    handler: async (config) => {
+        return await call(config, "/pricing/get", { method: "POST" });
+    },
+};
+const list_dns_records = {
+    name: "list_dns_records",
+    description: "List all DNS records for a domain in the authenticated account. Returns each record's id, type (A, AAAA, CNAME, MX, TXT, etc.), name (subdomain or empty for apex), content, ttl, and priority (where applicable). The `id` field is required when editing or deleting a specific record.",
+    inputSchema: {
+        domain: z
+            .string()
+            .min(3)
+            .describe("Fully qualified domain name registered at Porkbun, e.g. `example.com`"),
+    },
+    handler: async (config, args) => {
+        const domain = String(args.domain).toLowerCase();
+        return await call(config, `/dns/retrieve/${encodeURIComponent(domain)}`, { method: "GET" });
+    },
+};
+const get_ssl_bundle = {
+    name: "get_ssl_bundle",
+    description: "Retrieve the free Porkbun-issued SSL certificate bundle for a domain. Returns the certificate chain, private key, and public key (PEM-encoded strings). Porkbun automatically provisions Let's Encrypt certificates for all registered domains using Porkbun nameservers. Use this to install TLS on a server you control.",
+    inputSchema: {
+        domain: z
+            .string()
+            .min(3)
+            .describe("Fully qualified domain name registered at Porkbun, e.g. `example.com`"),
+    },
+    handler: async (config, args) => {
+        const domain = String(args.domain).toLowerCase();
+        return await call(config, `/ssl/retrieve/${encodeURIComponent(domain)}`, { method: "GET" });
+    },
+};
+export const tools = [
+    ping,
+    check_domain,
+    list_domains,
+    get_balance,
+    get_pricing,
+    list_dns_records,
+    get_ssl_bundle,
+];

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@porkbunllc/mcp-server",
+  "version": "0.1.0",
+  "description": "Porkbun MCP server — exposes the Porkbun v3 API as tools for AI agents (Claude Desktop, Cursor, etc.)",
+  "type": "module",
+  "bin": {
+    "porkbun-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch",
+    "prepublishOnly": "rm -rf dist && tsc"
+  },
+  "keywords": [
+    "mcp",
+    "porkbun",
+    "domain",
+    "dns",
+    "ai",
+    "agent",
+    "claude"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oborseth/Porkbun-MCP.git"
+  },
+  "bugs": {
+    "url": "https://github.com/oborseth/Porkbun-MCP/issues"
+  },
+  "homepage": "https://github.com/oborseth/Porkbun-MCP#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.1",
+    "typescript": "^6.0.3"
+  }
+}