TMDB MCP Server

Overview Schema Source Related Servers Discussions Admin

Search movies

search_movies

Read-only

Search TMDB movies by title to return compact summaries with the TMDB movie ID and pagination info, enabling other movie tools to fetch details.

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. region here only picks which country's release_date is shown per result (e.g. a title's US vs. India theatrical date) — verified live, it does not filter which movies match or reorder them; for actual region-based availability use get_watch_providers instead.

Input Schema

Name	Required	Description
`page`	No	1-based page number for pagination (TMDB returns up to 20 results per page, max 500).
`year`	No	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.
`query`	Yes	Movie title to search for.
`region`	No	ISO-3166-1 country code for region-specific results (default 'US').
`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.
`exact_year`	No	Match `year` against the original (primary) release year only, dropping every movie first released in another year. Requires `year`.
`include_adult`	No	Include adult (NSFW) results. Defaults to false.

Output Schema

Name	Required	Description	Default
`page`	Yes
`results`	Yes
`total_pages`	Yes
`total_results`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed14 schema fields changedv0.14.0Oct 24, 2026

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"
+]
```

Changed3 schema fields changedv0.10.1Jul 30, 2026

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
```

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})?$"
```

Changed5 schema fields changedv0.8.0Jul 22, 2026

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"
+}

First observedv0.3.0Jul 9, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Beyond the readOnly/openWorld annotations, it discloses return characteristics (compact summaries, required TMDB id, pagination info) and a non-obvious live-verified behavior of `region` that could otherwise mislead an agent. This is meaningful behavioral context, not repetition of structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose and return value, then moves into sibling routing and a high-value caveat about `region`. Every sentence carries actionable information for tool selection or invocation.

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?

Given the full schema, existing output schema, and annotations, the description supplies the remaining routing and behavioral context an agent needs. It covers the main trap (`region` semantics), the sibling alternative, and the downstream use of returned ids.

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 parameter documentation is already strong. The description still adds important meaning for `region`, explaining that it only selects which country's release_date is displayed rather than filtering or reordering results, which goes beyond the schema's basic ISO-code description.

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?

The description states a specific verb and resource ('Search TMDB movies by title') and explains what the tool returns: compact summaries with the TMDB id needed by related movie tools. It also distinguishes itself from the sibling search_multi, so an agent can route correctly without opening schemas.

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?

It gives explicit routing guidance: use this over search_multi when the result is known to be a movie. It also clarifies that `region` does not filter or reorder matches and points to get_watch_providers for actual region-based availability.

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