tvmaze-mcp-server

Tvmaze Get Episodes

tvmaze_get_episodes

Read-onlyIdempotent

List a show’s episodes with air times, runtimes, and synopses. Pass a season number to list one season, which is the cheaper path and the usual one; pass air_date to list the episodes dated to one day, the direct path to a single night of a daily show; omit both to walk the whole run, which is paged because a long-running series returns hundreds of episodes. Specials are excluded unless include_specials is set, and the number left out is reported.

Input Schema

TableJSON Schema

Name	Required	Description
`limit`	No	Maximum episodes to return in this call. Applies to every page, including a call that passes cursor. Raise it for a short series; the default keeps a long run inside a reasonable response size.
`cursor`	No	Continuation token from a previous call’s next_cursor. It carries only the position to resume from; the page size comes from limit. Omit for the first page.
`season`	No	Season number to list, as numbered in the season list from tvmaze_get_show. Omit, together with air_date, to list every episode of the series. Daily shows number seasons by calendar year.
`show_id`	Yes	TVmaze show id, from tvmaze_search_shows, tvmaze_lookup_show, or tvmaze_get_schedule.
`air_date`	No	Date to list, ISO 8601 (YYYY-MM-DD): the episodes the source dates to that day. It matches the source’s airdate, the broadcaster’s own programming day, so on a late-night slot it can differ by a day from the local_date an episode reports. Cannot be combined with season.
`timezone`	No	IANA timezone name for the air times, e.g. "America/Los_Angeles". Defaults to the server-configured timezone.
`include_specials`	No	Include specials alongside regular episodes. Off by default because specials roughly double the result count on a series that has many; when off, notice reports how many were left out.

Output Schema

TableJSON Schema

Name	Required	Description
`cap`	No	The page size applied to this call — its limit.
`show`	No	The show the episodes belong to.
`error`	No	Present when the call failed. Absent on success.
`shown`	No	Number of episodes returned on this page.
`notice`	No	Guidance when the page was truncated, when nothing was recorded, or when specials were filtered out — every one that applies, joined. Absent otherwise.
`season`	No	Season number listed. Absent when the whole run or one air date was listed.
`air_date`	No	Air date listed, YYYY-MM-DD. Absent unless air_date was given.
`episodes`	No	Episodes in airing order.
`has_more`	No	True when more episodes remain beyond this page.
`timezone`	No	IANA timezone the air times were rendered in.
`truncated`	No	True when the page limit was reached.
`totalCount`	No	Episodes matching before the page limit was applied.
`next_cursor`	No	Pass as cursor to fetch the next page. Absent on the last page.

Schema Changelog

Changes observed during successful MCP inspections.

Changed13 schema fields changedSep 22, 2026

addedInput schema / properties / air_date

Added value: +{
+  "description": "Date to list, ISO 8601 (YYYY-MM-DD): the episodes the source dates to that day. It matches the source’s airdate, the broadcaster’s own programming day, so on a late-night slot it can differ by a day from the local_date an episode reports. Cannot be combined with season.",
+  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+  "type": "string"
+}

changedInput schema / properties / cursor / description

Previous value: -"Continuation token from a previous call’s next_cursor. Omit for the first page."New value: +"Continuation token from a previous call’s next_cursor. It carries only the position to resume from; the page size comes from limit. Omit for the first page."

changedInput schema / properties / include_specials / description

Previous value: -"Include specials alongside regular episodes. Off by default because specials roughly double the result count on a series that has many."New value: +"Include specials alongside regular episodes. Off by default because specials roughly double the result count on a series that has many; when off, notice reports how many were left out."

changedInput schema / properties / limit / description

Previous value: -"Maximum episodes to return in one call. Raise it for a short series; the default keeps a long run inside a reasonable response size."New value: +"Maximum episodes to return in this call. Applies to every page, including a call that passes cursor. Raise it for a short series; the default keeps a long run inside a reasonable response size."

changedInput schema / properties / season / description

Previous value: -"Season number to list, as numbered in the season list from tvmaze_get_show. Omit to list every episode of the series. Daily shows number seasons by calendar year."New value: +"Season number to list, as numbered in the season list from tvmaze_get_show. Omit, together with air_date, to list every episode of the series. Daily shows number seasons by calendar year."

addedOutput schema / properties / air_date

Added value: +{
+  "description": "Air date listed, YYYY-MM-DD. Absent unless air_date was given.",
+  "type": "string"
+}

changedOutput schema / properties / cap / description

Previous value: -"The page limit that was applied."New value: +"The page size applied to this call — its limit."

changedOutput schema / properties / episodes / items / properties / local_date / description

Previous value: -"Calendar date the episode airs, in the requested timezone, ISO 8601 (YYYY-MM-DD)."New value: +"Calendar date the episode airs, ISO 8601 (YYYY-MM-DD). When time_known is true, the date in the requested timezone. When time_known is false, the source’s own announced air date, not timezone-converted — the same in every timezone."

changedOutput schema / properties / episodes / items / properties / type / description

Previous value: -"Episode classification: \"regular\", \"significant_special\", or \"insignificant_special\". Anything other than \"regular\" is a special, and specials are excluded from a whole-run listing unless include_specials is set."New value: +"Episode classification: \"regular\", \"significant_special\", or \"insignificant_special\". Anything other than \"regular\" is a special; tvmaze_get_episodes leaves specials out unless include_specials is set."

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `show_not_found`: No show exists with the given TVmaze id. `season_not_found`: The show has no season with the requested number. `invalid_timezone`: The timezone is not an IANA zone name the runtime recognizes. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `show_not_found`: No show exists with the given TVmaze id. `season_not_found`: The show has no season with the requested number. `invalid_date`: The air_date is well-formed but not a real calendar date. `invalid_timezone`: The timezone is not an IANA zone name the runtime recognizes. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "show_not_found",
-  "season_not_found",
-  "invalid_timezone"
-]New value: +[
+  "show_not_found",
+  "season_not_found",
+  "invalid_date",
+  "invalid_timezone"
+]

changedOutput schema / properties / notice / description

Previous value: -"Guidance when nothing was recorded, or when specials were filtered out of a season listing. Absent otherwise."New value: +"Guidance when the page was truncated, when nothing was recorded, or when specials were filtered out — every one that applies, joined. Absent otherwise."

changedOutput schema / properties / season / description

Previous value: -"Season number listed. Absent when the whole run was listed."New value: +"Season number listed. Absent when the whole run or one air date was listed."

First observedSep 20, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Beyond the readOnly/idempotent annotations, the description discloses paging behavior for long-running series, that specials are excluded by default, and that the count of omitted specials is reported. These are behavioral details an agent would not otherwise know.

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 sentences, front-loaded with the core purpose, then organized by parameter mode. No filler or repetition of schema details; every sentence contributes decision-relevant information.

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?

For a tool with seven parameters and an output schema, the description covers all invocation modes, pagination, specials behavior, and parameter tradeoffs. The presence of an output schema means return-value details do not need to be restated, so nothing essential is missing.

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 the baseline is 3; the description adds value by explaining the interaction between season, air_date, and omission of both, plus the semantic consequence of include_specials. Individual parameter formats remain in the schema, but the top-level description enriches the parameter model.

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?

The description opens with a specific verb and object: 'List a show’s episodes with air times, runtimes, and synopses.' It names the resource and the returned kinds of data clearly, and the three invocation modes distinguish this from sibling tools like tvmaze_get_next_episode or tvmaze_get_schedule.

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?

Explicitly states when to pass season, when to pass air_date, and when to omit both, including the tradeoffs ('cheaper path', 'direct path to a single night of a daily show', 'paged'). It also explains the default behavior for specials and how to override it, giving an agent concrete decision rules.

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

All tvmaze-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.