Skip to main content
Glama
TMDB MCP Server

TMDB MCP Server

Search movies

search_movies
Read-only

Search TMDB movies by title to get compact summaries, TMDB IDs for other movie tools, and pagination info. Filter by year, exact release year, language, and adult results.

Instructions

Search TMDB movies by title; returns compact summaries with the TMDB id that the other movie tools (get_movie, get_movie_credits, …) require, plus pagination info. Use this over search_multi when you already know the result is a movie. year/release_date are the original (primary) release, as everywhere except get_movie_releases, which shows the chosen country's date.

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": {
      "query": "<query>"
    },
    "name": "search_movies"
  }
}

Input Schema

NameRequiredDescriptionDefault
pageNo1-based page number for pagination (TMDB returns up to 20 results per page, max 500).
yearNoBias results toward this release year. Soft by default: it matches any of a movie's release dates, so re-releases and older films still appear (checked live: 'alien' with year 2003 ranks the 1979 Alien first). Set exact_year to match only the original release year.
queryYesMovie title to search for.
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
exact_yearNoMatch `year` against the original (primary) release year only, dropping movies first released in another year. Requires `year`.
include_adultNoInclude adult (NSFW) results.

Output Schema

NameRequiredDescriptionDefault
pageYes
resultsYes
total_pagesYes
total_resultsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed7 schema fields changedv0.15.0
    • changedInput schema / properties / exact_year / description
      Previous value: -"Match `year` against the original (primary) release year only, dropping every movie first released in another year. Requires `year`."New value: +"Match `year` against the original (primary) release year only, dropping movies first released in another year. Requires `year`."
    • addedInput schema / properties / include_adult / default
      Added value: +false
    • changedInput schema / properties / include_adult / description
      Previous value: -"Include adult (NSFW) results. Defaults to false."New value: +"Include adult (NSFW) results."
    • 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."
    • removedInput schema / properties / region
      Removed value: -{
      -  "description": "ISO-3166-1 country code for region-specific results (default 'US').",
      -  "pattern": "^[A-Z]{2}$",
      -  "type": "string"
      -}
    • changedInput schema / properties / year / description
      Previous value: -"Bias results toward this release year. Soft by default: it matches any of a movie's release dates, so re-releases and older films still appear (verified live: 'alien' with year 2003 ranks the 1979 Alien first). Set exact_year to match only the original release year."New value: +"Bias results toward this release year. Soft by default: it matches any of a movie's release dates, so re-releases and older films still appear (checked live: 'alien' with year 2003 ranks the 1979 Alien first). Set exact_year to match only the original release year."
  2. Changed14 schema fields changedv0.14.0
    • addedInput schema / properties / exact_year
      Added value: +{
      +  "description": "Match `year` against the original (primary) release year only, dropping every movie first released in another year. Requires `year`.",
      +  "type": "boolean"
      +}
    • 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."
    • changedInput schema / properties / year / description
      Previous value: -"Bias results toward this release year — TMDB's search 'year' filter is soft: some results outside this year can still appear (unlike discover_movies' year filter, a hard primary_release_year match). For an exact-year filter, use discover_movies instead."New value: +"Bias results toward this release year. Soft by default: it matches any of a movie's release dates, so re-releases and older films still appear (verified live: 'alien' with year 2003 ranks the 1979 Alien first). Set exact_year to match only the original release year."
    • removedOutput schema / properties / results / items / properties / overview / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / results / items / properties / overview / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / results / items / properties / poster_url / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / results / items / properties / poster_url / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / results / items / properties / vote_average / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / results / items / properties / vote_average / description
      Added value: +"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."
    • addedOutput schema / properties / results / items / properties / vote_average / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / results / items / properties / vote_count / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / results / items / properties / vote_count / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / results / items / properties / year / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / results / items / properties / year / type
      Added value: +[
      +  "number",
      +  "null"
      +]
  3. Changed3 schema fields changedv0.10.1
    • changedInput schema / properties / year / description
      Previous value: -"Filter by release year."New value: +"Bias results toward this release year — TMDB's search 'year' filter is soft: some results outside this year can still appear (unlike discover_movies' year filter, a hard primary_release_year match). For an exact-year filter, use discover_movies instead."
    • changedOutput schema / properties / results / items / properties / release_date / anyOf
      Previous value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "format": "date",
      +    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • addedOutput schema / properties / results / items / properties / release_date / default
      Added value: +null
  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. Changed5 schema fields changedv0.8.0
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / additionalProperties
      Added value: +false
    • changedInput schema / properties / page / description
      Previous value: -"1-based page number for pagination."New value: +"1-based page number for pagination (TMDB returns up to 20 results per page, max 500)."
    • changedInput schema / properties / page / maximum
      Previous value: -9007199254740991New value: +500
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "https://json-schema.org/draft/2020-12/schema",
      +  "additionalProperties": false,
      +  "properties": {
      +    "page": {
      +      "type": "number"
      +    },
      +    "results": {
      +      "items": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "id": {
      +            "type": "number"
      +          },
      +          "media_type": {
      +            "const": "movie",
      +            "type": "string"
      +          },
      +          "original_title": {
      +            "type": "string"
      +          },
      +          "overview": {
      +            "anyOf": [
      +              {
      +                "type": "string"
      +              },
      +              {
      +                "type": "null"
      +              }
      +            ]
      +          },
      +          "poster_url": {
      +            "anyOf": [
      +              {
      +                "type": "string"
      +              },
      +              {
      +                "type": "null"
      +              }
      +            ]
      +          },
      +          "release_date": {
      +            "anyOf": [
      +              {
      +                "type": "string"
      +              },
      +              {
      +                "type": "null"
      +              }
      +            ]
      +          },
      +          "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",
      +          "media_type",
      +          "year",
      +          "release_date",
      +          "vote_average",
      +          "vote_count",
      +          "overview",
      +          "poster_url"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "total_pages": {
      +      "type": "number"
      +    },
      +    "total_results": {
      +      "type": "number"
      +    }
      +  },
      +  "required": [
      +    "results",
      +    "page",
      +    "total_pages",
      +    "total_results"
      +  ],
      +  "type": "object"
      +}
  6. First observedv0.3.0

TDQS

A4.4/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and network behavior are covered. The description adds genuine context beyond that: results are 'compact summaries' carrying the TMDB id needed for follow-up calls, and pagination info is returned. It does not describe result caps or error behavior, but the annotations plus existing output schema lower the burden.

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 compact sentences, front-loaded with purpose and the sibling routing rule. Each sentence earns its place, though the trailing `release_date` reference adds mild cross-tool noise for a parameter this tool doesn't expose.

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?

With full schema coverage, an output schema, and readOnly/openWorld annotations, the remaining descriptive burden is small, and the definition covers purpose, sibling routing, output identity, and the year semantics. An agent has everything needed to call this correctly and use the result.

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 cross-tool semantics the schema cannot: that `year` matches the original (primary) release date 'as everywhere except get_movie_releases.' That is a real clarification of scope with a named exception. The mention of `release_date` as a parameter is slightly confusing since it isn't in this tool's schema.

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 ('Search TMDB movies by title') and immediately describes the output shape ('compact summaries with the TMDB id ... plus pagination info'). It also explicitly distinguishes itself from a named sibling (search_multi), so an agent can route without opening either 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 an explicit selection rule against an alternative: 'Use this over search_multi when you already know the result is a movie.' It also clarifies downstream usage (the returned TMDB id is required by get_movie, get_movie_credits), which tells the agent when this tool is the right first step in a chain.

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