Skip to main content
Glama

tvmaze-mcp-server

by io.github.cyanheads
OverviewDiscussionsAdmin

Tvmaze Get Cast

tvmaze_get_cast
Read-onlyIdempotent

List the credited cast of a show with the characters they play, optionally with crew; or list the guest cast of one episode, optionally with its guest crew such as the director and writers. Results are paged: cast rows come first, then crew rows, and each page splits them back into cast and crew. The source records no recurring-versus-guest distinction on a show’s cast list, so a name’s absence from it does not mean the performer never appeared — check an episode’s guest cast for that.

Input Schema

NameRequiredDescriptionDefault

No arguments

Output Schema

NameRequiredDescriptionDefault
capNoApplied page size, at most 250; present when clamped or more rows remain.
castNoCast credits on this page — for scope "show", the main cast; for scope "episode", that episode’s guest cast. Empty on a page past the last cast row.
crewNoCrew credits on this page — for scope "show", the show’s crew; for scope "episode", that episode’s guest crew. Present, possibly empty, whenever include_crew was set; crew rows follow every cast row, so a page that ends inside the cast carries none.
errorNoPresent when the call failed. Absent on success.
scopeNoWhich credit list was returned.
shownNoNumber of credits returned on this page.
noticeNoGuidance when the page was truncated, or when no cast is recorded — every one that applies, joined. Absent otherwise.
has_moreNoTrue when more credits remain beyond this page.
truncatedNoTrue when more matching credits remain.
cast_totalNoMatching cast credits across every page.
crew_totalNoMatching crew credits across every page. Present when include_crew was set.
subject_idNoTVmaze id the credits belong to — a show id or an episode id, matching scope.
totalCountNoMatching credits across every page, cast plus crew.
next_cursorNoPass as cursor to fetch the next page. Absent on the last page.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changed
    • changedInput schema / oneOf
      Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "cursor": {
-        "description": "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.",
-        "type": "string"
-      },
-      "include_crew": {
-        "default": false,
-        "description": "Also list the show’s crew credits — producers, creators, and other series-level roles, with no episode attribution. Off by default; a long-running series carries hundreds and they are rarely what a cast question is asking for.",
-        "type": "boolean"
-      },
-      "limit": {
-        "default": 50,
-        "description": "Maximum credits to return in this call, cast and crew together. Applies to every page, including a call that passes cursor. A long-running series carries over a thousand cast credits.",
-        "maximum": 250,
-        "minimum": 1,
-        "type": "integer"
-      },
-      "scope": {
-        "const": "show",
-        "description": "List the show’s main cast.",
-        "type": "string"
-      },
-      "show_id": {
-        "description": "TVmaze show id, from tvmaze_search_shows, tvmaze_lookup_show, or tvmaze_get_schedule.",
-        "exclusiveMinimum": 0,
-        "maximum": 9007199254740991,
-        "type": "integer"
-      }
-    },
-    "required": [
-      "scope",
-      "show_id"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "cursor": {
-        "description": "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.",
-        "type": "string"
-      },
-      "episode_id": {
-        "description": "TVmaze episode id, from tvmaze_get_episodes, tvmaze_get_next_episode, tvmaze_get_schedule, or tvmaze_get_show.",
-        "exclusiveMinimum": 0,
-        "maximum": 9007199254740991,
-        "type": "integer"
-      },
-      "include_crew": {
-        "default": false,
-        "description": "Also list the episode’s guest crew — who directed and wrote it, as TVmaze credits them. Off by default.",
-        "type": "boolean"
-      },
-      "limit": {
-        "default": 50,
-        "description": "Maximum credits to return in this call, cast and crew together. Applies to every page, including a call that passes cursor. A long-running series carries over a thousand cast credits.",
-        "maximum": 250,
-        "minimum": 1,
-        "type": "integer"
-      },
-      "scope": {
-        "const": "episode",
-        "description": "List one episode’s guest cast.",
-        "type": "string"
-      }
-    },
-    "required": [
-      "scope",
-      "episode_id"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "cursor": {
+        "description": "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.",
+        "type": "string"
+      },
+      "include_crew": {
+        "default": false,
+        "description": "Also list the show’s crew credits — producers, creators, and other series-level roles, with no episode attribution. Off by default; a long-running series carries hundreds and they are rarely what a cast question is asking for.",
+        "type": "boolean"
+      },
+      "limit": {
+        "default": 50,
+        "description": "Maximum credits to return in this call, cast and crew together. Requests above 250 are clamped to 250. Applies to every page, including a call that passes cursor. A long-running series carries over a thousand cast credits.",
+        "maximum": 9007199254740991,
+        "minimum": 1,
+        "type": "integer"
+      },
+      "name": {
+        "description": "Case-insensitive substring in performer, character, or crew role. Blank means no filter; crew is searched only with include_crew.",
+        "type": "string"
+      },
+      "scope": {
+        "const": "show",
+        "description": "List the show’s main cast.",
+        "type": "string"
+      },
+      "show_id": {
+        "description": "TVmaze show id, from tvmaze_search_shows, tvmaze_lookup_show, or tvmaze_get_schedule.",
+        "exclusiveMinimum": 0,
+        "maximum": 9007199254740991,
+        "type": "integer"
+      }
+    },
+    "required": [
+      "scope",
+      "show_id"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "cursor": {
+        "description": "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.",
+        "type": "string"
+      },
+      "episode_id": {
+        "description": "TVmaze episode id, from tvmaze_get_episodes, tvmaze_get_next_episode, tvmaze_get_schedule, or tvmaze_get_show.",
+        "exclusiveMinimum": 0,
+        "maximum": 9007199254740991,
+        "type": "integer"
+      },
+      "include_crew": {
+        "default": false,
+        "description": "Also list the episode’s guest crew — who directed and wrote it, as TVmaze credits them. Off by default.",
+        "type": "boolean"
+      },
+      "limit": {
+        "default": 50,
+        "description": "Maximum credits to return in this call, cast and crew together. Requests above 250 are clamped to 250. Applies to every page, including a call that passes cursor. A long-running series carries over a thousand cast credits.",
+        "maximum": 9007199254740991,
+        "minimum": 1,
+        "type": "integer"
+      },
+      "name": {
+        "description": "Case-insensitive substring in performer, character, or crew role. Blank means no filter; crew is searched only with include_crew.",
+        "type": "string"
+      },
+      "scope": {
+        "const": "episode",
+        "description": "List one episode’s guest cast.",
+        "type": "string"
+      }
+    },
+    "required": [
+      "scope",
+      "episode_id"
+    ],
+    "type": "object"
+  }
+]
    • changedOutput schema / properties / cap / description
      Previous value: -"The page size applied to this call — its limit."New value: +"Applied page size, at most 250; present when clamped or more rows remain."
    • changedOutput schema / properties / cast_total / description
      Previous value: -"Cast credits across every page."New value: +"Matching cast credits across every page."
    • changedOutput schema / properties / crew_total / description
      Previous value: -"Crew credits across every page. Present when include_crew was set."New value: +"Matching crew credits across every page. Present when include_crew was set."
    • changedOutput schema / properties / totalCount / description
      Previous value: -"Credits across every page, cast plus crew."New value: +"Matching credits across every page, cast plus crew."
    • changedOutput schema / properties / truncated / description
      Previous value: -"True when the page limit was reached."New value: +"True when more matching credits remain."
  2. Changed13 schema fields changed
    • changedInput schema / oneOf
      Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "include_crew": {
-        "default": false,
-        "description": "Also list crew credits — producers, writers, directors. Off by default; a long-running series carries dozens and they are rarely what a cast question is asking for.",
-        "type": "boolean"
-      },
-      "scope": {
-        "const": "show",
-        "description": "List the show’s main cast.",
-        "type": "string"
-      },
-      "show_id": {
-        "description": "TVmaze show id, from tvmaze_search_shows, tvmaze_lookup_show, or tvmaze_get_schedule.",
-        "exclusiveMinimum": 0,
-        "maximum": 9007199254740991,
-        "type": "integer"
-      }
-    },
-    "required": [
-      "scope",
-      "show_id"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "episode_id": {
-        "description": "TVmaze episode id, from tvmaze_get_episodes, tvmaze_get_next_episode, tvmaze_get_schedule, or tvmaze_get_show.",
-        "exclusiveMinimum": 0,
-        "maximum": 9007199254740991,
-        "type": "integer"
-      },
-      "scope": {
-        "const": "episode",
-        "description": "List one episode’s guest cast.",
-        "type": "string"
-      }
-    },
-    "required": [
-      "scope",
-      "episode_id"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "cursor": {
+        "description": "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.",
+        "type": "string"
+      },
+      "include_crew": {
+        "default": false,
+        "description": "Also list the show’s crew credits — producers, creators, and other series-level roles, with no episode attribution. Off by default; a long-running series carries hundreds and they are rarely what a cast question is asking for.",
+        "type": "boolean"
+      },
+      "limit": {
+        "default": 50,
+        "description": "Maximum credits to return in this call, cast and crew together. Applies to every page, including a call that passes cursor. A long-running series carries over a thousand cast credits.",
+        "maximum": 250,
+        "minimum": 1,
+        "type": "integer"
+      },
+      "scope": {
+        "const": "show",
+        "description": "List the show’s main cast.",
+        "type": "string"
+      },
+      "show_id": {
+        "description": "TVmaze show id, from tvmaze_search_shows, tvmaze_lookup_show, or tvmaze_get_schedule.",
+        "exclusiveMinimum": 0,
+        "maximum": 9007199254740991,
+        "type": "integer"
+      }
+    },
+    "required": [
+      "scope",
+      "show_id"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "cursor": {
+        "description": "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.",
+        "type": "string"
+      },
+      "episode_id": {
+        "description": "TVmaze episode id, from tvmaze_get_episodes, tvmaze_get_next_episode, tvmaze_get_schedule, or tvmaze_get_show.",
+        "exclusiveMinimum": 0,
+        "maximum": 9007199254740991,
+        "type": "integer"
+      },
+      "include_crew": {
+        "default": false,
+        "description": "Also list the episode’s guest crew — who directed and wrote it, as TVmaze credits them. Off by default.",
+        "type": "boolean"
+      },
+      "limit": {
+        "default": 50,
+        "description": "Maximum credits to return in this call, cast and crew together. Applies to every page, including a call that passes cursor. A long-running series carries over a thousand cast credits.",
+        "maximum": 250,
+        "minimum": 1,
+        "type": "integer"
+      },
+      "scope": {
+        "const": "episode",
+        "description": "List one episode’s guest cast.",
+        "type": "string"
+      }
+    },
+    "required": [
+      "scope",
+      "episode_id"
+    ],
+    "type": "object"
+  }
+]
    • changedOutput schema / anyOf
      Previous value: -[
-  {
-    "not": {
-      "required": [
-        "error"
-      ]
-    },
-    "required": [
-      "cast",
-      "scope",
-      "subject_id",
-      "totalCount"
-    ]
-  },
-  {
-    "required": [
-      "error"
-    ]
-  }
-]New value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "cast",
+      "cast_total",
+      "scope",
+      "subject_id",
+      "has_more",
+      "totalCount"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]
    • addedOutput schema / properties / cap
      Added value: +{
+  "description": "The page size applied to this call — its limit.",
+  "type": "number"
+}
    • changedOutput schema / properties / cast / description
      Previous value: -"Cast credits — for scope \"show\", the main cast; for scope \"episode\", that episode’s guest cast."New value: +"Cast credits on this page — for scope \"show\", the main cast; for scope \"episode\", that episode’s guest cast. Empty on a page past the last cast row."
    • addedOutput schema / properties / cast_total
      Added value: +{
+  "description": "Cast credits across every page.",
+  "type": "number"
+}
    • changedOutput schema / properties / crew / description
      Previous value: -"Crew credits. Present only when include_crew was set on a show query."New value: +"Crew credits on this page — for scope \"show\", the show’s crew; for scope \"episode\", that episode’s guest crew. Present, possibly empty, whenever include_crew was set; crew rows follow every cast row, so a page that ends inside the cast carries none."
    • addedOutput schema / properties / crew_total
      Added value: +{
+  "description": "Crew credits across every page. Present when include_crew was set.",
+  "type": "number"
+}
    • addedOutput schema / properties / has_more
      Added value: +{
+  "description": "True when more credits remain beyond this page.",
+  "type": "boolean"
+}
    • addedOutput schema / properties / next_cursor
      Added value: +{
+  "description": "Pass as cursor to fetch the next page. Absent on the last page.",
+  "type": "string"
+}
    • changedOutput schema / properties / notice / description
      Previous value: -"Guidance when no credits are recorded. Absent otherwise."New value: +"Guidance when the page was truncated, or when no cast is recorded — every one that applies, joined. Absent otherwise."
    • addedOutput schema / properties / shown
      Added value: +{
+  "description": "Number of credits returned on this page.",
+  "type": "number"
+}
    • changedOutput schema / properties / totalCount / description
      Previous value: -"Credits returned, cast plus crew."New value: +"Credits across every page, cast plus crew."
    • addedOutput schema / properties / truncated
      Added value: +{
+  "description": "True when the page limit was reached.",
+  "type": "boolean"
+}
  3. First observed

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint), so the bar is lower, and the description still adds non-obvious context: page composition is cast rows first then crew rows, and each page re-splits them, plus the source-data caveat that a show cast list carries no recurring-vs-guest distinction. The limit clamp and pagination mechanics live in the schema rather than here.

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?

Three sentences, each front-loaded with its purpose: capability first, then paging behavior, then the data-quality caveat. Dense but no filler, though the paging sentence ('each page splits them back into cast and crew') is slightly convoluted for the space it takes.

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?

Both mutually exclusive call shapes are described, the crew opt-in and its rationale are covered, pagination is explained, and the recurring-vs-guest caveat closes the main interpretive gap. With an output schema present, return-value details need not be restated, so nothing an agent needs to call this correctly is missing.

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 the schema already documents name, limit, cursor, scope, show_id/episode_id and include_crew in detail. The description reinforces the crew-gated filtering and paging semantics but adds no syntax or format meaning beyond what the schema provides, which is the baseline-3 case.

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 specific verbs and resources across both call shapes: 'List the credited cast of a show with the characters they play' and 'list the guest cast of one episode'. The show-vs-episode distinction is explicit, so an agent can tell this apart from tvmaze_get_show or tvmaze_get_episodes without opening the schema.

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

Usage Guidelines4/5

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

Gives clear selection context: use show scope for a show's main cast, episode scope for an episode's guest cast, and include_crew only when crew is actually wanted. It also tells the agent to fall back to an episode's guest cast when a name is absent from a show list. No exclusions or explicit sibling routing (e.g. which tool to use for person data) are stated.

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 toolsInspect
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.

Resources