Porkbun MCP

🚀 porkbun-mcp

porkbun-mcp 是一個用於Porkbun域名和DNS的MCP服務器。藉助它，你可以通過任何兼容MCP的客戶端來檢查和管理Porkbun的域名、DNS記錄等信息，並且操作安全可靠。

🚀 快速開始

1) 前提條件

• Node.js >=20
• Porkbun API憑證：
  • PORKBUN_API_KEY
  • PORKBUN_SECRET_KEY
• 在Porkbun面板中，目標域名必須標記為可通過API訪問（“available via API”）。如果禁用了域名級別的API訪問，僅使用賬戶級別的密鑰是不夠的。

獲取密鑰的步驟如下：

• 登錄Porkbun。
• 打開賬戶設置並進入API訪問頁面。
• 生成/複製：
  • PORKBUN_API_KEY（API密鑰）
  • PORKBUN_SECRET_KEY（秘密API密鑰）
• 在域名設置中，確保要管理的每個域名都啟用了API訪問。

在本地安裝依賴（用於開發）：

npm install
npm run build

2) 快速本地運行（標準輸入輸出）

只讀模式：

PORKBUN_API_KEY=your_key \
PORKBUN_SECRET_KEY=your_secret \
node dist/index.js

啟用寫操作：

PORKBUN_API_KEY=your_key \
PORKBUN_SECRET_KEY=your_secret \
PORKBUN_GET_MUDDY=true \
node dist/index.js --get-muddy

3) 驗證CLI連接

node dist/index.js --help

✨ 主要特性

• 安全操作：默認情況下為只讀行為，進行修改操作的工具需要顯式開啟寫模式，場景工具默認 dry_run: true。
• 功能豐富：可管理域名和名稱服務器、DNS記錄、DNSSEC、SSL證書包以及URL轉發。
• 多客戶端集成：支持Cursor、Claude Desktop等多種MCP客戶端。

📦 安裝指南

前提條件

• Node.js >=20
• 準備好Porkbun API憑證：PORKBUN_API_KEY 和 PORKBUN_SECRET_KEY。
• 確保目標域名在Porkbun面板中標記為可通過API訪問。

安裝步驟

在本地安裝依賴（用於開發）：

npm install
npm run build

💻 使用示例

基礎用法

dns_query 按記錄ID查詢

{
  "domain": "example.com",
  "selector": {
    "record_id": "123456789"
  }
}

dns_upsert 計劃模式

{
  "domain": "example.com",
  "match": {
    "type": "A",
    "subdomain": "www"
  },
  "target": {
    "content": "203.0.113.10",
    "ttl": 300
  },
  "dry_run": true
}

高級用法

domains_check_bulk 批量檢查域名

{
  "domains": ["example.com", "example.net", "example.org"],
  "concurrency": 1,
  "respect_limits": true,
  "delay_ms": 11000,
  "stop_on_rate_limit": true
}

dns_batch_apply 批量應用DNS記錄

{
  "domain": "example.com",
  "desired_records": [
    {
      "type": "A",
      "subdomain": "",
      "content": "198.51.100.42",
      "ttl": 300
    }
  ],
  "mode": "plan",
  "strategy": "merge",
  "max_changes": 5
}

📚 詳細文檔

MCP客戶端集成

GitHub的README不支持原生標籤，因此本節使用可摺疊的“類標籤”塊。如果你之後將文檔遷移到文檔網站（如Docusaurus/Nextra），可以將相同的代碼片段用作真正的標籤。

基礎服務器代碼片段（安全只讀）

{
  "porkbun-mcp": {
    "command": "npx",
    "args": ["-y", "porkbun-mcp"],
    "env": {
      "PORKBUN_API_KEY": "your_porkbun_api_key",
      "PORKBUN_SECRET_KEY": "your_porkbun_secret_api_key"
    }
  }
}

{
  "mcpServers": {
    "porkbun-mcp": {
      "command": "npx",
      "args": ["-y", "porkbun-mcp"],
      "env": {
        "PORKBUN_API_KEY": "your_porkbun_api_key",
        "PORKBUN_SECRET_KEY": "your_porkbun_secret_api_key"
      }
    }
  }
}

{
  "mcpServers": {
    "porkbun-mcp": {
      "command": "npx",
      "args": ["-y", "porkbun-mcp"],
      "env": {
        "PORKBUN_API_KEY": "your_porkbun_api_key",
        "PORKBUN_SECRET_KEY": "your_porkbun_secret_api_key"
      }
    }
  }
}

{
  "mcpServers": {
    "porkbun-mcp": {
      "command": "npx",
      "args": ["-y", "porkbun-mcp"],
      "env": {
        "PORKBUN_API_KEY": "your_porkbun_api_key",
        "PORKBUN_SECRET_KEY": "your_porkbun_secret_api_key"
      }
    }
  }
}

啟用寫模式

{
  "mcpServers": {
    "porkbun-mcp": {
      "command": "npx",
      "args": ["-y", "porkbun-mcp", "--get-muddy"],
      "env": {
        "PORKBUN_API_KEY": "your_porkbun_api_key",
        "PORKBUN_SECRET_KEY": "your_porkbun_secret_api_key"
      }
    }
  }
}

啟用域名創建（危險操作）

{
  "mcpServers": {
    "porkbun-mcp": {
      "command": "npx",
      "args": ["-y", "porkbun-mcp", "--get-muddy", "--enable-domain-create"],
      "env": {
        "PORKBUN_API_KEY": "your_porkbun_api_key",
        "PORKBUN_SECRET_KEY": "your_porkbun_secret_api_key"
      }
    }
  }
}

重要提示：Porkbun API域名註冊的前提條件：

• 你的Porkbun賬戶過去必須至少註冊過一個域名（對於新賬戶，首次購買可能需要通過Web界面完成）。
• 你的電子郵件地址和電話號碼必須經過驗證。
• 你的賬戶必須有足夠的信用額度（API註冊將從賬戶信用額度中扣除費用）。
• cost 必須以美分提供，並且必須與域名檢查返回的值相匹配（最短期限 * 價格）。
• 你必須明確接受條款（在本服務器中為 agree_to_terms=true，對應Porkbun的 agreeToTerms="yes"）。

參考：Porkbun API v3文檔（請參閱“Domain Create”和“Domain Check”）：https://porkbun.com/api/json/v3/documentation

首次成功調用

在MCP客戶端中配置完成後，從以下操作開始：

• ping
• pricing_get

然後嘗試一個讀取流程：

• 針對你的域名執行 dns_list

在進行任何寫操作之前，先以 dry_run 模式運行場景工具。

安全模型

• 除非設置了 --get-muddy 或 PORKBUN_GET_MUDDY=true，否則寫操作將被阻止。
• 場景工具設計為先規劃再應用。
• 破壞性工具包含明確的限制和確認步驟。
• API憑證是賬戶級別的，但Porkbun中的域名級API權限仍然適用。
• 域名註冊（domains_create）默認禁用，需要：
  • 寫模式（--get-muddy）
  • 顯式啟用標誌（--enable-domain-create 或 PORKBUN_ENABLE_DOMAIN_CREATE=true）
  • dry_run=false + confirm_apply=true + agree_to_terms=true

環境變量

• PORKBUN_API_KEY（必需）
• PORKBUN_SECRET_KEY（必需）
• PORKBUN_GET_MUDDY（可選）
• PORKBUN_ENABLE_DOMAIN_CREATE（可選，危險）

CLI選項

• --get-muddy
• --enable-domain-create（危險）
• --transport stdio
• --ipv4-only-api
• --help

--get-muddy 的含義

--get-muddy 啟用寫模式。

如果不使用該選項，服務器將保持安全的只讀行為；使用該選項後，允許進行修改操作（如創建、編輯、刪除、更新DNS和域名設置）。

僅在以下情況下使用此模式：

• 你準備好進行實際的基礎設施更改。
• 你的域名在Porkbun中已啟用API訪問。
• 你已經通過讀取調用或 dry_run 流程驗證了計劃。

工具覆蓋範圍

• 連接性：ping、pricing_get
• 域名：列出、管理名稱服務器、URL轉發、膠水記錄（獲取/創建/更新/刪除）、檢查可用性
• DNS：列出/獲取/創建/編輯/刪除（包括按名稱/類型）
• DNSSEC：列出/創建/刪除
• SSL：檢索證書包

場景工具：

• dns_query
• dns_upsert
• domain_health_check
• dns_remove
• domain_redirect_ensure
• domain_cutover_web
• dns_batch_apply

初學者輔助工具：

• dns_audit
• dns_setup
• email_dns_setup
• update_server_ip
• subdomain_setup

詳細文檔：

🔧 技術細節

Porkbun操作通常具有重複性，並且在時間緊迫的情況下存在風險。本項目將Porkbun API作為MCP工具公開，使AI助手能夠一致地執行域名工作流程，並設置了安全防護措施。

📄 許可證

本項目採用MIT許可證。

其他說明

安全注意事項

• 切勿將真實的API密鑰提交到git。
• 建議使用本地環境變量或秘密管理器。
• 將寫模式視為生產訪問權限。

開發

npm install
npm run build

本地運行：

npm run dev

貢獻

歡迎貢獻代碼。在提交PR之前，請閱讀 。