Skip to main content
Glama
TMDB MCP Server

TMDB MCP Server

Get compact movie card(s)

get_movies
Read-only

Fetch compact cards for 1–20 movies by TMDB ID in one call, including title, year, genres, vote average, and optional ratings. Use it when you need headline info only; request full details separately.

Instructions

Get a compact card (title, year, genres, vote average, and opt-in ratings) for 1-20 movies by TMDB id in one call. Trimmed: no overview, cast, budget, certifications, production companies, etc. Use it for a single id too when you only need that headline info, not just for checking many at once. Call get_movie 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_movies"
  }
}

Input Schema

NameRequiredDescriptionDefault
idsYesTMDB movie ids to fetch (1-20). Get them from search_movies/discover_movies/get_similar/get_movie_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"
      -      },
      -      "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"
      -          }
      -        ]
      -      },
      -      "title": {
      -        "type": "string"
      -      },
      -      "vote_average": {
      -        "anyOf": [
      -          {
      -            "type": "number"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      },
      -      "vote_count": {
      -        "anyOf": [
      -          {
      -            "type": "number"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      },
      -      "year": {
      -        "anyOf": [
      -          {
      -            "type": "number"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      }
      -    },
      -    "required": [
      -      "id",
      -      "year",
      -      "genres",
      -      "vote_average",
      -      "vote_count",
      -      "found"
      -    ],
      -    "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"
      +      },
      +      "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"
      +          }
      +        ]
      +      },
      +      "title": {
      +        "type": "string"
      +      },
      +      "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",
      +      "year",
      +      "genres",
      +      "vote_average",
      +      "vote_count",
      +      "found"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "found": {
      +        "const": false,
      +        "type": "boolean"
      +      },
      +      "id": {
      +        "type": "number"
      +      },
      +      "reason": {
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "found",
      +      "id",
      +      "reason"
      +    ],
      +    "type": "object"
      +  }
      +]
  3. Addedv0.10.1
  4. Removedv0.8.1
  5. 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})?$"
  6. 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 declare readOnlyHint and openWorldHint, but the description adds genuinely new behavior: per-id failure is isolated ('never fails the whole call'), failures return {id, found:false, reason}, results preserve input order, and callers should read reason before concluding the id doesn't exist. The only gap is that it doesn't restate rate-limit or cost characteristics of the ratings option beyond what the schema already says.

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 what the tool returns and its scope, then exclusions, then the sibling alternative, then failure semantics in priority order. It is dense and every sentence carries information, though the parenthetical field list and exclusion list make it longer than strictly necessary.

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, yet the description still surfaces the one return-shape detail an agent must not miss: partial failures come back as {id, found:false, reason} in input order. Combined with the sibling routing and scope limits, an agent has everything needed to call and interpret this tool correctly.

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, but the description adds real meaning: the ids parameter is framed as a 1-20 batch with per-entry failure semantics and order preservation, and ratings are described as 'opt-in'. It does not re-explain language localization, which is fine since the schema covers it thoroughly.

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 ('Get a compact card ... for 1-20 movies by TMDB id in one call') and enumerates exactly what the card contains (title, year, genres, vote average, opt-in ratings). It also states the negative space ('no overview, cast, budget, certifications, production companies'), which makes it immediately distinguishable from get_movie.

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 routing: use this tool for compact headline info, call get_movie instead for full details including region-specific certification. It even pre-empts a likely misuse case by saying it is appropriate for a single id when only headline info is needed, not just for bulk lookups.

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