Porkbun MCP

porkbun-mcp

用于管理 Porkbun 域名和 DNS 的 MCP 服务。

可通过任何兼容 MCP 的客户端检查和管理：

• 域名和名称服务器
• DNS 记录
• DNSSEC
• SSL 证书包
• URL 转发

专为安全操作而构建：

• 默认采用只读模式
• 修改类工具需要显式启用写入模式
• 场景工具默认设置为 dry_run: true

为什么要做这个项目

Porkbun 操作往往重复繁琐，而且在时间紧迫时容易出错。 本项目将 Porkbun API 封装为 MCP 工具，让 AI 助手能够在防护措施的约束下，以一致的方式执行域名工作流。

3 分钟快速设置

1）准备工作

• Node.js >=20
• Porkbun API 凭据：
  • PORKBUN_API_KEY
  • PORKBUN_SECRET_KEY
• 在 Porkbun 控制面板中，目标域名必须标记为可通过 API 访问（“available via API”）。 如果域名级别的 API 访问权限已停用，仅有账户级密钥是不够的。

获取密钥的方法：

• 登录 Porkbun。
• 打开账户设置，前往 API Access。
• 生成或复制：
  • PORKBUN_API_KEY（API Key）
  • PORKBUN_SECRET_KEY（Secret API Key）
• 在域名设置中，确保你要管理的每个域名都已启用 API 访问权限。

在本地安装依赖（用于开发）：

npm install
npm run build

2）快速本地运行（stdio）

只读模式：

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

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"
      }
    }
  }
}

使用 npx 启用写入模式

{
  "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 账户过去必须至少注册过一个域名（对于新账户，首次购买可能需要通过网页界面完成）。
• 你的电子邮箱地址和电话号码必须经过验证。
• 账户中必须有足够的余额（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 转发、Glue 记录（获取/创建/更新/删除）、可用性
• 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

实用示例

按记录 ID 使用 dns_query：

{
  "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 计划：

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

安全说明

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

开发

npm install
npm run build

本地运行：

npm run dev

贡献

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

许可证

MIT