Skip to main content
Glama
thenavidm

Beehiiv MCP Server

by thenavidm
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

List podcast episodes

podcasts_list_episodes
Read-onlyIdempotent

Retrieve podcast episodes for a publication and show, with filters for status, ordering, and pagination to review drafts, scheduled, published, or archived content.

Instructions

List podcast episodes. Reads account data. OAuth integrations require podcasts:read.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
pageNo**Offset-based pagination (deprecated)**: Page number for offset-based pagination. Please migrate to cursor-based pagination using the `cursor` parameter.
limitNoA limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10.
cursorNo**Cursor-based pagination (recommended)**: Use this opaque cursor token to fetch the next page of results. Obtain the value from `next_cursor` in a previous response.
statusNoOptionally filter the results by the status of the episode. `draft` - Not yet published. `scheduled` - Scheduled for future publication. `published` - Available via web and RSS. `archived` - No longer available via web or RSS.
accountNoNamed private account from BEEHIIV_ACCOUNTS. Defaults to BEEHIIV_DEFAULT_ACCOUNT or the first configured account.
order_byNoThe field that the results are sorted by. Defaults to `displayed_date` `created` - The time in which the episode was first created. `updated` - The time the episode was last updated. `publish_date` - The exact time the system published the episode (when it went live), not the scheduled time the user set. `displayed_date` - The time displayed in place of the `publish_date`. Uses a custom display date if set, otherwise the scheduled time the user set for publication, otherwise the `publish_date`, otherwise the creation date. For imported episodes, the original feed's `pubDate` is stored as the custom display date. This is the same field used to order episodes in the podcast's RSS feed.displayed_date
all_pagesNoRead successive cursor pages, bounded by max_items (default 1000).
directionNoThe direction that the results are sorted in. Defaults to desc `asc` - Ascending, sorts from smallest to largest. `desc` - Descending, sorts from largest to smallest.asc
max_itemsNoMaximum records when all_pages=true. Returns continuation cursor and truncation.
publication_idYesThe prefixed ID of the publication object
podcast_show_idYesThe prefixed ID of the podcast

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv2.0.0

TDQS

B3.4/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond them — that it reads account data and requires the podcasts:read scope — but says nothing about pagination semantics or result caps.

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

Conciseness5/5

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

Three short sentences that lead with the action and then stack the permission facts; nothing is redundant or padded.

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 an 11-parameter tool this is thin, but the schema fully documents every parameter (including the deprecated page vs recommended cursor guidance) and annotations carry the safety profile, so the description's gaps are minor. Auth/scope coverage is the key addition and it is present.

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% with rich per-parameter docs (pagination tradeoffs, ordering, status enum, account selection), so the schema does the heavy lifting. The description adds no parameter-level meaning, so the baseline 3 applies.

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

Purpose4/5

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

States a specific verb and resource ('List podcast episodes'), which clearly separates it from podcasts_get_episode and podcasts_list_podcasts. It is unambiguous but does not go out of its way to contrast with the sibling list/get tools beyond the name itself.

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

Usage Guidelines2/5

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

The description offers no when-to-use guidance: it never says when to pick this over podcasts_get_episode, nor when to use cursor vs page vs all_pages. 'Reads account data' and the OAuth scope note are auth/permission facts, not usage routing.

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