Skip to main content
Glama
Sign In
Official Porkbun MCP Server

Official Porkbun MCP Server

by oborseth
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

List Domains

list_domains
Read-onlyIdempotent

List domains in your Porkbun account and filter by name, TLD, expiration, auto-renew, or API access to find renewal targets and operable domains.

Instructions

List domains in the authenticated Porkbun account. Returns one page (up to 1000) with metadata: expire date, auto-renew, security lock, WHOIS privacy, API access opt-in, and notLocal flag.

Filters (all optional):

  • domain: exact match. Returns 0 or 1.

  • name_contains: substring search on domain name.

  • tlds: limit to these TLDs (no leading dot).

  • expiring_within_days: only domains expiring within N days. Useful for renewal automation.

  • added_after / added_before: when the domain joined this account at Porkbun, by registration or transfer (addedDate). Pass the newest addedDate already seen as added_after to fetch only new domains.

  • created_after / created_before: registry creation date (createDate); a transferred-in domain keeps its original one.

  • expires_after / expires_before: expiry window by date.

  • auto_renew: 'yes' or 'no'.

  • api_access: 'yes' or 'no'. Filter to domains an API key can actually operate on — eliminates API_ACCESS_DISABLED errors downstream.

  • sort_name: 'domain' | 'tld' | 'create_date' | 'added_date' | 'expire_date'. Default expire_date.

Dates are YYYY-MM-DD or YYYY-MM-DD HH:MM:SS, UTC. *_after includes the moment, *_before excludes it.

  • sort_direction: 'asc' | 'desc'. Default asc.

For a single domain by name, use get_domain instead — cleaner shape and 404-on-not-found semantics.

Input Schema

NameRequiredDescriptionDefault
tldsNoLimit to these TLDs (no leading dot). Example: ['com', 'io']
startNoPagination offset. Default 0.
domainNoExact domain match — returns 0 or 1 result.
sort_nameNoSort field.
api_accessNoFilter to domains opted in to API access.
auto_renewNoFilter to domains with auto-renew on or off.
added_afterNoOnly domains added to the account (registered or transferred in) at or after this date/date-time, UTC.
added_beforeNoOnly domains added to the account before this date/date-time, UTC.
created_afterNoOnly domains whose registry creation date is at or after this date/date-time, UTC.
expires_afterNoOnly domains expiring at or after this date/date-time, UTC.
name_containsNoCase-insensitive substring on the full domain name.
created_beforeNoOnly domains whose registry creation date is before this date/date-time, UTC.
expires_beforeNoOnly domains expiring before this date/date-time, UTC.
include_labelsNoInclude user-defined domain labels in the response.
sort_directionNoSort direction.
expiring_within_daysNoOnly domains expiring within this many days from now.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed7 schema fields changedv0.57.0
    • addedInput schema / properties / added_after
      Added value: +{
+  "description": "Only domains added to the account (registered or transferred in) at or after this date/date-time, UTC.",
+  "type": "string"
+}
    • addedInput schema / properties / added_before
      Added value: +{
+  "description": "Only domains added to the account before this date/date-time, UTC.",
+  "type": "string"
+}
    • addedInput schema / properties / created_after
      Added value: +{
+  "description": "Only domains whose registry creation date is at or after this date/date-time, UTC.",
+  "type": "string"
+}
    • addedInput schema / properties / created_before
      Added value: +{
+  "description": "Only domains whose registry creation date is before this date/date-time, UTC.",
+  "type": "string"
+}
    • addedInput schema / properties / expires_after
      Added value: +{
+  "description": "Only domains expiring at or after this date/date-time, UTC.",
+  "type": "string"
+}
    • addedInput schema / properties / expires_before
      Added value: +{
+  "description": "Only domains expiring before this date/date-time, UTC.",
+  "type": "string"
+}
    • changedInput schema / properties / sort_name / enum
      Previous value: -[
-  "domain",
-  "tld",
-  "create_date",
-  "expire_date"
-]New value: +[
+  "domain",
+  "tld",
+  "create_date",
+  "added_date",
+  "expire_date"
+]
  2. First observedv0.4.1

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real context on top: single-page result capped at 1000, the field set returned, and the date-window inclusivity convention ('*_after includes the moment, *_before excludes it'). It does not say how to detect or advance to a next page beyond the offset, which keeps it just below a 5.

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-loaded purpose and return shape, then a scannable per-filter list, then the alternative-tool pointer. Long overall, but justified by 16 parameters; a few bullets restate schema text almost verbatim (tlds, auto_renew, sort_direction) and could be trimmed.

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

Completeness4/5

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

For a 16-param, zero-required read tool with no output schema, the description covers return contents, page size, date semantics, and sibling routing, which is enough to call it correctly. The remaining gap is pagination mechanics — nothing explains how an agent knows more pages exist or when to stop paging.

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

Parameters4/5

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

Schema coverage is 100%, so baseline would be 3; the description earns more by disambiguating the three date families (addedDate vs createDate vs expireDate), noting a transferred-in domain keeps its original createDate, and explaining the incremental-sync idiom of passing the newest addedDate as added_after. It adds little on start/include_labels, which are left entirely to the schema.

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?

Opens with a specific verb + resource + scope ('List domains in the authenticated Porkbun account') and immediately states the return cardinality ('one page, up to 1000') plus the metadata fields returned. It explicitly distinguishes itself from the sibling get_domain, so an agent can route correctly without opening either 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?

Names the alternative (get_domain) and the condition that selects it ('for a single domain by name... cleaner shape and 404-on-not-found semantics'). It also gives use-case guidance per filter, e.g. expiring_within_days 'useful for renewal automation' and api_access filtering to avoid API_ACCESS_DISABLED errors downstream.

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