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

详细文档：docs/scenario-tools.md

🔧 技术细节

Porkbun操作通常具有重复性，并且在时间紧迫的情况下存在风险。本项目将Porkbun API作为MCP工具公开，使AI助手能够一致地执行域名工作流程，并设置了安全防护措施。

📄 许可证

本项目采用MIT许可证。

其他说明

安全注意事项

• 切勿将真实的API密钥提交到git。
• 建议使用本地环境变量或秘密管理器。
• 将写模式视为生产访问权限。

开发

npm install
npm run build

本地运行：

npm run dev

贡献

欢迎贡献代码。在提交PR之前，请阅读 CONTRIBUTING.md。