Skip to main content
Glama
TMDB MCP Server

TMDB MCP Server

Get compact TV show card(s)

get_tv_shows
Read-only

Fetch compact summary cards for 1-20 TV shows by TMDB id in one call, showing year, genres, vote average and season/episode counts to quickly compare candidates and spot miniseries without 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. Otherwise trimmed: no overview, episode list, networks, certifications, etc. Use it for a single id too when you only need that headline info, not just for checking many at once. Call get_tv instead for the full details of a title (including region-specific certification). An id that fails to load (unknown, or hit by an upstream error such as a rate limit) never fails the whole call: that entry comes back {id, found:false, reason} instead, in the same order as ids; read reason before concluding the id doesn't exist.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "ids": "<ids>"
    },
    "name": "get_tv_shows"
  }
}

Input Schema

NameRequiredDescriptionDefault
idsYesTMDB TV show ids to fetch (1-20). Get them from search_tv/discover_tv/get_similar/get_tv_recommendations/etc.
languageNoResponse language (ISO-639-1, optionally with a region), e.g. 'ru-RU' or 'en-US'; pass the user's language when it isn't the default. Localizes titles/overviews/genre names. 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.en-US
include_ratingsNoAdd compact IMDb/Rotten Tomatoes/Metacritic ratings from OMDb to every card (requires OMDB_API_KEY). Costs one extra OMDb lookup per id, so a large batch means a burst of OMDb calls; mind OMDb's own rate limit. Off by default here, unlike get_movie/get_tv.

Output Schema

NameRequiredDescriptionDefault
resultsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.15.0
    • addedInput schema / properties / include_ratings / default
      Added value: +false
    • changedInput schema / properties / include_ratings / description
      Previous value: -"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."New value: +"Add compact IMDb/Rotten Tomatoes/Metacritic ratings from OMDb to every card (requires OMDB_API_KEY). Costs one extra OMDb lookup per id, so a large batch means a burst of OMDb calls; mind OMDb's own rate limit. Off by default here, unlike get_movie/get_tv."
    • addedInput schema / properties / language / default
      Added value: +"en-US"
    • 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. 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."New value: +"Response language (ISO-639-1, optionally with a region), e.g. 'ru-RU' or 'en-US'; pass the user's language when it isn't the default. Localizes titles/overviews/genre names. 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."
  2. Changed2 schema fields changedv0.14.0
    • 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"
      +  }
      +]
  3. Changed1 schema field changedv0.10.1
    • removedInput schema / properties / region
      Removed value: -{
      -  "description": "ISO-3166-1 country code for region-specific results (default 'US').",
      -  "pattern": "^[A-Z]{2}$",
      -  "type": "string"
      -}
  4. Changed2 schema fields changedv0.8.1
    • removedInput schema / properties / language / minLength
      Removed value: -2
    • addedInput schema / properties / language / pattern
      Added value: +"^[a-z]{2}(-[A-Z]{2})?$"
  5. Addedv0.8.0

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already cover read-only and open-world status, but the description adds real behavioral context beyond them: per-id failure isolation with `{id, found:false, reason}` returned in input order, the instruction to read `reason` before concluding an id is unknown, and the OMDb cost/rate-limit implication of include_ratings. The only missing piece is response ordering/pagination detail, which the output schema likely covers.

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 core action and payload contents, then alternatives, then failure semantics — a sensible order with almost no filler. It runs long and the mid-sentence aside about single-id use is slightly buried, keeping it off a 5.

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?

Complete for a batch read tool: it covers scope, sibling routing, trimmed fields, cost trade-offs, and partial-failure behavior, while the existing output schema carries return-shape detail. Nothing an agent needs to call it correctly or interpret a partial result 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 baseline is 3, and the description still adds meaning: it frames the batch size as 1-20, flags ratings as 'opt-in', and ties the failure-reason semantics to the `ids` ordering. It does not add new syntax or format detail beyond the schema for language or include_ratings, so it stays below 5.

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 and resource (compact card for 1-20 TV shows by TMDB id), enumerates exactly what the card contains, and explicitly contrasts with the sibling get_tv. An agent can distinguish this from get_tv, get_tv_season, or discover_tv without opening any 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?

Gives explicit when-to-use (spot short/miniseries across many candidates, or a single id needing only headline info) and when-not-to-use (call get_tv for full details including region-specific certification). It even preempts the wrong inference that this is batch-only.

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