TMDB MCP Server

Overview Schema Source Related Servers Discussions Admin

Get compact movie card(s)

get_movies

Read-only

Fetch compact headline cards—title, year, genres, vote average, and optional ratings—for 1–20 TMDB movie IDs in one call; unknown IDs return a found:false entry.

Instructions

Get a compact card — title, year, genres, vote average, and (opt-in) ratings — for 1-20 movies by TMDB id in one call. Deliberately trimmed (no overview, cast, budget, certifications, production companies, etc.): use this for a single id too when you only need that headline info and not the full get_movie payload, not just for checking many at once. Call get_movie 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 movie ids to fetch (1-20). Get them from search_movies/discover_movies/get_similar/get_movie_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"
-      },
-      "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"
+  }
+]

Addedv0.10.1Jul 30, 2026
Removedv0.8.1Jul 26, 2026
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?

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses graceful per-id failure with a `{id, found:false, reason}` shape, guarantees result ordering matches `ids`, and warns about a burst of OMDb calls and rate limits when include_ratings is set. This is exactly the behavioral context annotations cannot carry.

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 resource and field list, then the sibling routing, then the failure semantics. Every sentence carries information, though the parenthetical enumerations make it denser than strictly necessary; it is long but not padded.

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 3-parameter read tool: an output schema exists so return structure need not be restated, and the description still documents the one non-obvious return case (per-id not-found entries). Sibling routing, defaults, and rate-limit caveats are all covered.

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 already 100%, so the baseline is 3, but the description adds value the schema does not: it explains that include_ratings enriches every card via OMDb, that its default is false here (unlike get_movie/get_tv), and that batches amplify OMDb traffic. `ids` and `language` are covered by the schema and not repeated, which is appropriate.

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 — title, year, genres, vote average, and (opt-in) ratings — for 1-20 movies by TMDB id') with explicit scope (1-20 ids, trimmed field set). It distinguishes itself from the sibling get_movie by naming the exact fields it excludes and what the sibling provides.

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 guidance including the non-obvious case ('use this for a single id too when you only need that headline info'), and names the alternative with its selection condition ('Call get_movie instead when you need the full details ... including region-specific certification'). No inference required.

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