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

1. Clone the repository:

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

2. Create environment configuration:

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

3. Edit .env with your Porkbun API credentials:

PORKBUN_API_KEY=your_api_key_here
PORKBUN_SECRET_API_KEY=your_secret_api_key_here

4. Build and start the server:

make build
make up

5. 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

1. Log in to your Porkbun account
2. Go to API Access
3. Create API keys
4. 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

1. Never commit .env file - It contains your API credentials
2. Restrict CORS in production - Update allow_origins in src/main.py
3. Use HTTPS in production - Deploy behind a reverse proxy with SSL
4. Rotate API keys regularly - Generate new keys at porkbun.com/account/api
5. Monitor API usage - Check Porkbun dashboard for unusual activity
6. 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:

1. MCP Transport Layer - FastAPI with fastapi_mcp for Streamable HTTP
2. FastAPI Application Layer - RESTful endpoints with Pydantic validation
3. 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:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Copyright (c) 2025 Myroslav Tryhubets

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