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:
/healthand/healthzfor 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```bash
git clone https://github.com/lesleslie/porkbun-dns-mcp.git
cd porkbun-dns-mcp
uv sync --group dev
### Run With Credentials```bash
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.```bash
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:```json
{
"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```bash
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
| Tool | Purpose | Required Inputs |
|------|---------|-----------------|
| `list_dns_records` | List all DNS records for a domain | `domain` |
| `get_dns_record` | Retrieve one DNS record by ID | `domain`, `record_id` |
| `create_dns_record` | Create a DNS record | `domain`, `record_type`, `name`, `content` |
| `edit_dns_record` | Update selected fields on a DNS record | `domain`, `record_id` |
| `delete_dns_record` | Delete a DNS record | `domain`, `record_id` |
Supported record types are `A`, `AAAA`, `CNAME`, `MX`, `TXT`, `NS`, `SRV`, `CAA`, and `ALIAS`.
Tool responses follow a consistent `ToolResponse` shape:```json
{
"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.
| Setting | Environment Variable | Default |
|---|---|---|
| API key | PORKBUN_DNS_API_KEY |
empty |
| Secret key | PORKBUN_DNS_SECRET_KEY |
empty |
| Base URL | PORKBUN_DNS_BASE_URL |
https://porkbun.com/api/json/v3 |
| Timeout | PORKBUN_DNS_TIMEOUT |
30.0 |
| Max retries | PORKBUN_DNS_MAX_RETRIES |
3 |
| HTTP host | PORKBUN_DNS_HTTP_HOST |
127.0.0.1 |
| HTTP port | PORKBUN_DNS_HTTP_PORT |
3042 |
| Log level | PORKBUN_DNS_LOG_LEVEL |
INFO |
| JSON logs | PORKBUN_DNS_LOG_JSON |
true |
| Enable HTTP transport | PORKBUN_DNS_ENABLE_HTTP_TRANSPORT |
false |
Project Structure```text
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```bash
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:bash
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_recordandedit_dns_recordcalls 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.
