TMDB MCP Server

Overview Schema Source Related Servers Discussions Admin

Get compact TV show card(s)

get_tv_shows

Read-only

Fetch compact cards for 1–20 TV shows by TMDB ID in one call to compare headline details like year, genres, vote average, season/episode counts, and optional ratings without full per-title lookups.

Instructions

Get a compact card — name, year, genres, vote average, season/episode counts, and (opt-in) ratings — for 1-20 TV shows by TMDB id in one call. A quick way to spot short/miniseries shows (low episode count) across many candidates without a per-title get_tv call. Deliberately trimmed otherwise (no overview, the actual episode list, networks, certifications, etc.): use this for a single id too when you only need that headline info and not the full get_tv payload, not just for checking many at once. Call get_tv instead when you need the full details for a title (including region-specific certification). A bad/unknown id never fails the whole call — that entry comes back {id, found:false, reason} instead, in the same order as ids.

Input Schema

Name	Required	Description
`ids`	Yes	TMDB TV show ids to fetch (1-20). Get them from search_tv/discover_tv/get_similar/get_tv_recommendations/etc.
`language`	No	Override the response language (ISO-639-1, optionally with a region), e.g. 'ru-RU' or 'en-US'. Localizes titles/overviews/genre names. Defaults to the server's TMDB_LANGUAGE. A well-formed code TMDB has no translation for (e.g. 'xx') is not an error: overviews come back null, movies/shows keep their original-language title, and episodes get a generic 'Episode N' name.
`include_ratings`	No	If true, enrich every card with compact IMDb/Rotten Tomatoes/Metacritic ratings from OMDb (requires OMDB_API_KEY) — one extra OMDb lookup per id, so a large batch means a burst of OMDb calls; mind OMDb's own rate limit. Unlike get_movie/get_tv, defaults to false (off) here.

Output Schema

Name	Required	Description	Default
`results`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.14.0Oct 24, 2026

changedInput schema / properties / language / description

Previous value: -"Override the response language (ISO-639-1, optionally with a region), e.g. 'ru-RU' or 'en-US'. Localizes titles/overviews/genre names. Defaults to the server's TMDB_LANGUAGE."New value: +"Override the response language (ISO-639-1, optionally with a region), e.g. 'ru-RU' or 'en-US'. Localizes titles/overviews/genre names. Defaults to the server's TMDB_LANGUAGE. A well-formed code TMDB has no translation for (e.g. 'xx') is not an error: overviews come back null, movies/shows keep their original-language title, and episodes get a generic 'Episode N' name."

changedOutput schema / properties / results / items / oneOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "found": {
-        "const": true,
-        "type": "boolean"
-      },
-      "genres": {
-        "items": {
-          "type": "string"
-        },
-        "type": "array"
-      },
-      "id": {
-        "type": "number"
-      },
-      "name": {
-        "type": "string"
-      },
-      "number_of_episodes": {
-        "anyOf": [
-          {
-            "type": "number"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "number_of_seasons": {
-        "anyOf": [
-          {
-            "type": "number"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "ratings": {
-        "oneOf": [
-          {
-            "additionalProperties": false,
-            "properties": {
-              "found": {
-                "const": false,
-                "type": "boolean"
-              },
-              "reason": {
-                "type": "string"
-              }
-            },
-            "required": [
-              "found",
-              "reason"
-            ],
-            "type": "object"
-          },
-          {
-            "additionalProperties": false,
-            "properties": {
-              "found": {
-                "const": true,
-                "type": "boolean"
-              },
-              "imdb_rating": {
-                "anyOf": [
-                  {
-                    "type": "string"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ]
-              },
-              "metascore": {
-                "anyOf": [
-                  {
-                    "type": "string"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ]
-              },
-              "rotten_tomatoes": {
-                "anyOf": [
-                  {
-                    "type": "string"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ]
-              }
-            },
-            "required": [
-              "found",
-              "imdb_rating",
-              "rotten_tomatoes",
-              "metascore"
-            ],
-            "type": "object"
-          }
-        ]
-      },
-      "vote_average": {
-        "anyOf": [
-          {
-            "type": "number"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "vote_count": {
-        "anyOf": [
-          {
-            "type": "number"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "year": {
-        "anyOf": [
-          {
-            "type": "number"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      }
-    },
-    "required": [
-      "id",
-      "genres",
-      "vote_average",
-      "vote_count",
-      "number_of_seasons",
-      "number_of_episodes",
-      "found",
-      "year"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "found": {
-        "const": false,
-        "type": "boolean"
-      },
-      "id": {
-        "type": "number"
-      },
-      "reason": {
-        "type": "string"
-      }
-    },
-    "required": [
-      "found",
-      "id",
-      "reason"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "found": {
+        "const": true,
+        "type": "boolean"
+      },
+      "genres": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "id": {
+        "type": "number"
+      },
+      "name": {
+        "type": "string"
+      },
+      "number_of_episodes": {
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "number_of_seasons": {
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "ratings": {
+        "oneOf": [
+          {
+            "additionalProperties": false,
+            "properties": {
+              "found": {
+                "const": false,
+                "type": "boolean"
+              },
+              "reason": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "found",
+              "reason"
+            ],
+            "type": "object"
+          },
+          {
+            "additionalProperties": false,
+            "properties": {
+              "found": {
+                "const": true,
+                "type": "boolean"
+              },
+              "imdb_rating": {
+                "description": "IMDb user score, 0-10, as a string, e.g. '6.5'. Not TMDB's `vote_average`.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "metascore": {
+                "description": "Metacritic critic score, 0-100 scale, as a string, e.g. '67'.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "rotten_tomatoes": {
+                "description": "Rotten Tomatoes Tomatometer — the percentage of positive critic reviews, as a string including the sign, e.g. '79%'. Not a 0-10 or 0-100 score.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              }
+            },
+            "required": [
+              "found",
+              "imdb_rating",
+              "rotten_tomatoes",
+              "metascore"
+            ],
+            "type": "object"
+          }
+        ]
+      },
+      "vote_average": {
+        "description": "TMDB's own 0-10 user score. A different audience and scale from the IMDb/RT/Metacritic scores get_movie/get_tv return as `ratings` — don't compare, average or substitute across the two.",
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "vote_count": {
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "year": {
+        "type": [
+          "number",
+          "null"
+        ]
+      }
+    },
+    "required": [
+      "id",
+      "genres",
+      "vote_average",
+      "year",
+      "vote_count",
+      "number_of_seasons",
+      "number_of_episodes",
+      "found"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "found": {
+        "const": false,
+        "type": "boolean"
+      },
+      "id": {
+        "type": "number"
+      },
+      "reason": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "found",
+      "id",
+      "reason"
+    ],
+    "type": "object"
+  }
+]

Changed1 schema field changedv0.10.1Jul 30, 2026

removedInput schema / properties / region

Removed value: -{
-  "description": "ISO-3166-1 country code for region-specific results (default 'US').",
-  "pattern": "^[A-Z]{2}$",
-  "type": "string"
-}

Changed2 schema fields changedv0.8.1Jul 26, 2026
- removedInput schema / properties / language / minLength
```
Removed value: -2
```
- addedInput schema / properties / language / pattern
```
Added value: +"^[a-z]{2}(-[A-Z]{2})?$"
```
Addedv0.8.0Jul 22, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only declare readOnlyHint/openWorldHint; the description adds genuinely non-obvious behavior — trimmed payload contents, opt-in ratings that cost one OMDb lookup per id with its own rate limit, a default that differs from get_movie/get_tv, and partial-failure semantics where a bad id returns `{id, found:false, reason}` in input order rather than failing the batch.

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 with the payload shape right after the verb, and every sentence carries operational information. The nested parenthetical clauses and the self-correcting 'not just for checking many at once' aside make it denser than it needs to be.

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?

An output schema exists, so return values need no prose, yet the description still spells out the per-entry error shape and ordering. Combined with the exclusions list, the batch cap, and the ratings cost model, an agent has everything needed to call this correctly instead of get_tv.

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 a 3 is the baseline; the description goes beyond it by explaining that `include_ratings` is opt-in and defaults to false here (unlike sibling tools) and that each id incurs a lookup. It also reinforces the 1-20 batch bound and the ordering guarantee for `ids`, though it adds nothing about the `language` parameter beyond what the schema documents.

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 ('Get a compact card'), the exact fields returned, the batch limit (1-20), and the keying by TMDB id. It is immediately distinguishable from get_tv and get_tv_season because it names what is deliberately excluded from the payload.

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 prescribes both directions: use get_tv 'when you need the full details for a title (including region-specific certification)', and use this tool even for a single id when only headline info is needed. It also names the motivating use case (spotting miniseries via low episode count).

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