Skip to main content
Glama
oborseth

Official Porkbun MCP Server

by oborseth
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Create DNS Record

create_dns_record
Idempotent

Add an A, AAAA, CNAME, MX, TXT or other DNS record to a domain in your Porkbun account. Returns the new record ID so it can be updated or deleted later.

Instructions

Create a DNS record on a domain in the authenticated account. Returns the new record's id so it can be referenced by update_dns_record and delete_dns_record. For the name field: omit or pass empty string for the apex/root, otherwise pass the subdomain prefix only (e.g. www, not www.example.com). For MX and SRV records, set prio (priority). Free, doesn't spend account credit. If a record with this exact name, type and content already exists the call fails with DUPLICATE_RECORD and returns that record's id in existingId — use it rather than retrying or creating a variant. If a CNAME would share a name with another record type (forbidden by RFC 1034) the call fails with RECORD_CONFLICT and lists the blocking rows in conflictingRecords; delete those or pick another name.

Check warnings in the response and pass it on. Porkbun keeps a DNS zone for every domain in the account whether or not the domain is delegated to Porkbun's nameservers, so this write succeeds either way. If the domain points somewhere else, the response is still SUCCESS but carries a warnings string naming the nameservers that actually answer — the record exists and nothing resolves differently. Do not report plain success in that case: either make the change at the provider that runs those nameservers, or offer update_nameservers to point the domain at Porkbun.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
ttlNoTime-to-live in seconds. Minimum 60. Defaults to 600 if omitted.
nameNoSubdomain prefix (no domain). Empty string or omitted = apex. Examples: `www`, `mail`, `api.staging`.
prioNoPriority — required for MX and SRV records, ignored otherwise.
typeYesRecord type. Common: A, AAAA, CNAME, MX, TXT.
domainYesDomain to add the record to, e.g. `example.com`
contentYesRecord value (e.g. an IP for A, a hostname for CNAME, the text body for TXT).
dry_runNoIf true, validate only — returns wouldSucceed without creating the record.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.39.4
    • addedInput schema / properties / dry_run
      Added value: +{
+  "description": "If true, validate only — returns wouldSucceed without creating the record.",
+  "type": "boolean"
+}
  2. First observedv0.4.1

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well past the annotations, which only declare non-readOnly, non-destructive, idempotent, closed-world. The description discloses cost ('free, doesn't spend account credit'), the two error codes and their payload fields, the dry_run validation path, and the important quirk that a write can return SUCCESS with a warnings string when the zone is not actually authoritative. Minor ding: it never reconciles the duplicate-fails behavior with the idempotentHint=true annotation, leaving a small ambiguity about repeat-call semantics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads purpose and return value before drilling into edge cases, and every paragraph addresses a real failure mode. It is still fairly long with heavy bolding and a mid-paragraph meta-instruction ('Check warnings in the response and pass it on'), which is slightly awkward but not wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description must carry return semantics — and it does: id for downstream update/delete, existingId on DUPLICATE_RECORD, conflictingRecords on RECORD_CONFLICT, warnings on non-authoritative zones, and wouldSucceed under dry_run. Combined with full schema coverage, an agent has everything needed to invoke and interpret the call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so ttl, name, prio, domain and content are already documented in the schema; per the rubric that sets a baseline of 3. The description restates the apex/prefix rule for `name` and the MX/SRV requirement for `prio`, which corroborates but adds no syntax or format detail beyond what the schema already carries.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Create a DNS record on a domain') and immediately disambiguates from siblings by naming update_dns_record and delete_dns_record as consumers of the returned id. An agent can distinguish this from create_cloudflare_record or import_dns_records without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete routing conditions: duplicate content → reuse existingId instead of retrying or creating a variant; CNAME name clash → delete conflictingRecords or pick another name; non-Porkbun nameservers → make the change at the other provider or call update_nameservers. It states both when to use and when not to, plus named alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools