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 アカウントで、過去に少なくとも 1 つのドメインを登録している必要があります（新規アカウントの場合、最初の購入は Web UI から行う必要がある場合があります）。
• メールアドレスと電話番号の認証が完了している必要があります。
• アカウントに十分なクレジットが必要です（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

次に、読み取りのフローを 1 つ試します。

• 自分のドメインに対して 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

実用例

レコード 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