Porkbun DNS MCP Server

MCP server for managing Porkbun DNS records through a FastMCP interface.

Version: 0.2.0 Status: Standalone FastMCP server

Quick Links

• Overview
• Capabilities
• Quick Start
• MCP Server Configuration
• Tool Reference
• Configuration
• Development

Quality & CI

Crackerjack is the standard quality-control and CI/CD gate for Porkbun DNS MCP changes. Local verification should mirror the Crackerjack workflow.

Overview

Porkbun DNS MCP exposes DNS record management workflows through a FastMCP server. It is focused on record lookup, creation, update, and deletion for domains managed through Porkbun while keeping provider credentials and request validation in a narrow integration boundary.

This server is intentionally separate from porkbun-domain-mcp. DNS owns record-level operations; domain owns registration, renewal, transfer, and pricing workflows.

Capabilities

Implemented tool surface (the first 5 bullets are MCP tools registered via @app.tool(); the last two are HTTP endpoints / internal helpers, not MCP tools — see the Tool Reference and Health Checks sections for the exact surface):

• Record listing: list all DNS records for a domain
• Record lookup: retrieve a specific DNS record by ID
• Record creation: create A, AAAA, CNAME, MX, TXT, NS, SRV, CAA, or ALIAS records
• Record editing: update selected fields on an existing DNS record
• Record deletion: remove a DNS record by ID
• Credential health metadata: PorkbunDNSSettings.has_credentials() reports whether API credentials are configured (internal helper, not an MCP tool)
• HTTP health routes: /health and /healthz for MCP client and process supervision checks (Starlette routes, not MCP tools)

Quick Start

Prerequisites

• Python 3.13+
• UV package manager
• Porkbun API key and secret key

Local Setup

git clone https://github.com/lesleslie/porkbun-dns-mcp.git
cd porkbun-dns-mcp
uv sync --group dev

Run With Credentials

export PORKBUN_DNS_API_KEY="your-api-key"
export PORKBUN_DNS_SECRET_KEY="your-secret-key"
uv run porkbun-dns-mcp start
uv run porkbun-dns-mcp health

The default HTTP bind is 127.0.0.1:3042.

CLI Commands

The CLI is built with mcp-common and provides the standard lifecycle command surface used by FastMCP servers.

uv run porkbun-dns-mcp start      # Start the HTTP MCP server
uv run porkbun-dns-mcp stop       # Stop the managed server process
uv run porkbun-dns-mcp restart    # Restart the managed server process
uv run porkbun-dns-mcp status     # Show process status
uv run porkbun-dns-mcp health     # Run the local health probe

MCP Server Configuration

Claude / Codex Style Configuration

Add the server to an MCP client configuration:

{
  "mcpServers": {
    "porkbun-dns": {
      "command": "uv",
      "args": ["run", "porkbun-dns-mcp", "start"],
      "cwd": "/Users/les/Projects/porkbun-dns-mcp",
      "env": {
        "PORKBUN_DNS_API_KEY": "your-api-key",
        "PORKBUN_DNS_SECRET_KEY": "your-secret-key"
      }
    }
  }
}

Use your secret manager for live credentials rather than committing them to client config.

Health Checks

curl http://127.0.0.1:3042/health
curl http://127.0.0.1:3042/healthz

Installation via Claude Code marketplace

This repo ships a Claude Code plugin manifest (.claude-plugin/plugin.json) plus a colocated .mcp.json and three slash commands in commands/. To install, register the www-mcp-servers marketplace with Claude Code, then install the plugin by name. Once installed, the slash commands /porkbun-dns-records, /porkbun-dns-list, and /porkbun-dns-create become available alongside the mcp__porkbun-dns__* tools.

Tool Reference

Supported record types are A, AAAA, CNAME, MX, TXT, NS, SRV, CAA, and ALIAS.

Tool responses follow a consistent ToolResponse shape:

{
  "success": true,
  "message": "Found 4 DNS records for example.com",
  "data": {},
  "error": null,
  "next_steps": []
}

Configuration

Committed defaults live in settings/porkbun-dns.yaml. Runtime overrides should come from environment variables or a local .env file that is not committed.

Project Structure

porkbun_dns_mcp/
  cli.py              # mcp-common lifecycle CLI
  client.py           # Porkbun DNS API client boundary
  config.py           # Pydantic settings and logging
  models.py           # Typed DNS record models
  server.py           # FastMCP application factory
  tools/dns_tools.py  # Registered MCP tools
settings/
  porkbun-dns.yaml    # Committed defaults
tests/
  test_schema_validation.py

Development

uv sync --group dev
uv run pytest
uv run ruff check porkbun_dns_mcp tests
uv run ruff format porkbun_dns_mcp tests
uv run pyright porkbun_dns_mcp

Use targeted tests when isolating schema behavior:

uv run pytest tests/test_schema_validation.py -v

Security Notes

• Do not commit Porkbun API keys, secret keys, real customer domains, or sensitive record values.
• Treat DNS mutations as production-impacting operations.
• Review generated delete_dns_record and edit_dns_record calls before exposing them to unattended agent workflows.
• Scrub real domain details from fixtures, screenshots, and troubleshooting logs.

Built on Oneiric for runtime configuration and mcp-common for the FastMCP baseline. Crackerjack gates every commit.