Porkbun MCP Server

A production-ready Model Context Protocol (MCP) server that exposes the complete Porkbun domain and DNS management API to AI assistants like Claude and LibreChat.

Features

27 MCP Tools providing comprehensive Porkbun API access:

Authentication & General (2 tools)

porkbun_ping - Test API connectivity and get your IP
porkbun_get_pricing - Get domain pricing for all TLDs

Domain Management (4 tools)

porkbun_list_domains - List all domains in account
porkbun_check_domain - Check domain availability
porkbun_update_nameservers - Update nameservers at registry
porkbun_get_nameservers - Get current nameservers

URL Forwarding (3 tools)

porkbun_add_url_forward - Create URL redirects (301/302)
porkbun_get_url_forwarding - List URL forwards
porkbun_delete_url_forward - Delete URL forwards

Glue Records (4 tools)

porkbun_create_glue_record - Create glue records
porkbun_update_glue_record - Update glue records
porkbun_delete_glue_record - Delete glue records
porkbun_get_glue_records - List glue records

DNS Records (8 tools)

porkbun_create_dns_record - Create DNS records (A, AAAA, CNAME, MX, TXT, NS, SRV, etc.)
porkbun_edit_dns_record - Edit DNS record by ID
porkbun_edit_dns_records_by_name_type - Bulk edit by subdomain/type
porkbun_delete_dns_record - Delete DNS record by ID
porkbun_delete_dns_records_by_name_type - Bulk delete by subdomain/type
porkbun_retrieve_dns_records - Get all or specific DNS records
porkbun_retrieve_dns_records_by_name_type - Get records by subdomain/type

DNSSEC (3 tools)

porkbun_create_dnssec_record - Create DNSSEC records
porkbun_get_dnssec_records - List DNSSEC records
porkbun_delete_dnssec_record - Delete DNSSEC records

SSL Certificates (1 tool)

porkbun_retrieve_ssl_bundle - Get SSL certificate bundle

Quick Start

Prerequisites

Docker and Docker Compose
Porkbun API credentials from porkbun.com/account/api
API access must be enabled for your domains in the Porkbun dashboard

Installation

Clone the repository:

git clone https://github.com/myroslavtryhubets/porkbun-mcp.git
cd porkbun-mcp

Create environment configuration:

make install
# Or manually:
cp .env.example .env

Edit .env with your Porkbun API credentials:

PORKBUN_API_KEY=your_api_key_here
PORKBUN_SECRET_API_KEY=your_secret_api_key_here

Build and start the server:

make build
make up

Verify the server is running:

make test
# Or manually:
curl http://localhost:8000/health
curl http://localhost:8000/

Configuration

Environment Variables

Variable	Required	Default	Description
`PORKBUN_API_KEY`	Yes	-	Your Porkbun API key
`PORKBUN_SECRET_API_KEY`	Yes	-	Your Porkbun secret API key
`PORKBUN_BASE_URL`	No	`https://api.porkbun.com/api/json/v3`	Porkbun API base URL
`TIMEOUT`	No	`30`	Request timeout in seconds
`MCP_PORT`	No	`8000`	MCP server port

Getting Porkbun API Credentials

Log in to your Porkbun account
Go to API Access
Create API keys
Enable API access for the domains you want to manage

MCP Client Configuration

LibreChat Configuration

Method 1: Environment Variable

Add to your LibreChat .env file:

MCP_SERVERS='{"porkbun":{"url":"http://localhost:8000/porkbun/mcp","name":"Porkbun Domain & DNS","type":"streamable-http","instructions":"You are an assistant with access to Porkbun domain and DNS management. Use these tools to help users manage their domains, configure DNS records, set up URL forwarding, and maintain domain security. Always confirm destructive operations before executing."}}'

Method 2: Configuration File

Add to librechat.yaml:

mcpServers:
  porkbun:
    url: "http://localhost:8000/porkbun/mcp"
    name: "Porkbun Domain & DNS"
    type: streamable-http  # Use 'type', not 'transport'
    instructions: |
      You are an assistant with access to Porkbun domain and DNS management.
      
      Available capabilities:
      - Domain management (list, check availability, nameservers)
      - DNS record management (create, edit, delete A/AAAA/CNAME/MX/TXT/etc.)
      - URL forwarding setup
      - Glue record management
      - DNSSEC configuration
      - SSL certificate retrieval
      
      Always confirm destructive operations (delete, bulk operations) with the user first.
    timeout: 120000

Claude Desktop Configuration

Add to claude_desktop_config.json:

Location:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Configuration:

{
  "mcpServers": {
    "porkbun": {
      "url": "http://localhost:8000/porkbun/mcp",
      "transport": "http"
    }
  }
}

Usage Examples

Example Conversations with AI Assistant

Check domain availability:

User: "Is example.com available for registration?"
Assistant: [Uses porkbun_check_domain]

List domains:

User: "Show me all my domains"
Assistant: [Uses porkbun_list_domains]

Create DNS record:

User: "Add an A record for www.example.com pointing to 1.2.3.4"
Assistant: [Uses porkbun_create_dns_record with domain="example.com", record_type="A", content="1.2.3.4", name="www"]

Set up URL forwarding:

User: "Forward old-site.com to https://new-site.com with a permanent redirect"
Assistant: [Uses porkbun_add_url_forward with domain="old-site.com", location="https://new-site.com", forward_type="permanent"]

View DNS records:

User: "What are the DNS records for example.com?"
Assistant: [Uses porkbun_retrieve_dns_records]

API Documentation

Once the server is running, access:

OpenAPI Documentation: http://localhost:8000/docs
OpenAPI JSON: http://localhost:8000/porkbun/openapi.json
Health Check: http://localhost:8000/health
Server Info: http://localhost:8000/

Development

Project Structure

porkbun-mcp/
├── src/
│   ├── __init__.py          # Package initialization
│   ├── main.py              # FastAPI app with MCP integration
│   └── models.py            # Pydantic configuration models
├── services/
│   ├── __init__.py
│   └── client.py            # Porkbun API client
├── ci/
│   └── semver.json          # Version metadata
├── Dockerfile               # Container build configuration
├── docker-compose.yml       # Service orchestration
├── requirements.txt         # Python dependencies
├── Makefile                 # Convenience commands
├── .env.example             # Environment template
├── .gitignore              # Git ignore rules
└── README.md               # This file

Makefile Commands

make help       # Show all available commands
make build      # Build Docker image
make up         # Start server
make down       # Stop server
make restart    # Restart server
make logs       # View server logs
make clean      # Remove containers and images
make test       # Test server endpoints
make install    # Create .env from template

Running Without Docker

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Create .env file with your credentials
cp .env.example .env
# Edit .env with your API keys

# Run the server
python -m src.main

Logging

Logs are written to:

Console: Docker logs (view with make logs)
File: porkbun_mcp.log (inside container)

Log format:

%(asctime)s - %(name)s - %(levelname)s - %(message)s

Sensitive data (API keys) are automatically masked in logs.

Security Best Practices

Never commit .env file - It contains your API credentials
Restrict CORS in production - Update allow_origins in src/main.py
Use HTTPS in production - Deploy behind a reverse proxy with SSL
Rotate API keys regularly - Generate new keys at porkbun.com/account/api
Monitor API usage - Check Porkbun dashboard for unusual activity
Enable 2FA - Protect your Porkbun account with two-factor authentication

Troubleshooting

Server won't start

Check logs:

make logs

Common issues:

Missing API credentials in .env
Port 8000 already in use (change MCP_PORT in .env)
Invalid API keys (verify at porkbun.com/account/api)

API calls fail

Check API access:

Verify API access is enabled for your domains in Porkbun dashboard
Test with ping endpoint: curl http://localhost:8000/porkbun/mcp
Check that API keys have correct permissions

MCP client can't connect

LibreChat:

Verify type: streamable-http (not transport)
Check URL matches server: http://localhost:8000/porkbun/mcp
Restart LibreChat after configuration changes

Claude Desktop:

Verify transport: http in config
Check URL is accessible from Claude Desktop
Restart Claude Desktop after configuration changes

Rate Limits

Porkbun API has rate limits:

Domain checks: Limited (rate limit info returned in response)
Other operations: Generally generous limits

The server will return error messages if rate limits are exceeded.

Architecture

This MCP server follows the three-layer architecture pattern:

MCP Transport Layer - FastAPI with fastapi_mcp for Streamable HTTP
FastAPI Application Layer - RESTful endpoints with Pydantic validation
External API Client Layer - Async httpx client for Porkbun API

Key Technologies

FastAPI - Modern async web framework
fastapi_mcp - MCP protocol integration
httpx - Async HTTP client
Pydantic - Configuration and validation
uvicorn - ASGI server
Docker - Containerization

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

License

MIT License - see LICENSE file for details.

Changelog

Version 1.0.0 (2025-10-29)

Initial release with 27 MCP tools:

Complete Porkbun API coverage
Domain management
DNS record operations
URL forwarding
Glue records
DNSSEC support
SSL certificate retrieval
Docker deployment
LibreChat and Claude Desktop support