TMDB MCP Server

Overview Schema Source Related Servers Discussions Admin

Get IMDb/RT/Metacritic ratings

get_ratings

Read-only

Look up IMDb, Rotten Tomatoes and Metacritic ratings, awards summaries and age ratings for a film, show or episode by IMDb id or title, with year and type to disambiguate same-name titles.

Instructions

Look up IMDb, Rotten Tomatoes and Metacritic ratings, an awards summary (major-award wins/nominations — Oscars, Emmys, Golden Globes, etc.; free text, not a structured count, for the whole film/show — or for one episode, given an episode's imdb_id — never one person), and OMDb's own age rating (rated), from OMDb by IMDb id (preferred, e.g. 'tt0133093') or by title (+ optional year/type). Prefer get_movie/get_tv when you have a TMDB id — they already include this. Requires OMDB_API_KEY. One of imdb_id or title is required; omitting both returns an error. A no-match lookup is not an error: it returns {found:false, reason}. A title lookup resolves to whichever single entry OMDb picks, reports no runner-up, and cannot be validated against anything — so it can silently return a different work of the same name. Verified live: title:'Halloween' with no year returns the 1978 original (tt0077651, IMDb 7.7, RT 97%), not the 2018 film titled exactly the same (tt1502407, IMDb 6.5, RT 79%). Always read back the returned imdb_id/title/year to confirm which work you actually got, and pass year (and type) whenever you know them. When you only have a title, prefer search_movies/search_tv → get_movie/get_tv instead: that path matches by imdb_id and additionally drops an OMDb hit whose release year is more than two years from TMDB's, which this tool's title path has no way to do.

Input Schema

Name	Required	Description
`type`	No	Restrict a title lookup to this entry type. Verified live: without it, OMDb's own title match can silently prefer one type over another when the exact same title exists as more than one — e.g. a title lookup for 'Chuck' with no `type` returns the 2007 TV series, not the unrelated 2016 movie of the same name, with no signal the movie was ever in contention. Only affects a title lookup; has no effect when imdb_id is given (already unambiguous).
`year`	No	Year, to disambiguate a title.
`title`	No	Movie/show title (used when imdb_id is absent).
`imdb_id`	No	IMDb title id. Takes precedence over title when both are given.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.14.0Oct 24, 2026

changedOutput schema / oneOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "found": {
-        "const": false,
-        "type": "boolean"
-      },
-      "reason": {
-        "type": "string"
-      }
-    },
-    "required": [
-      "found",
-      "reason"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "awards": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "found": {
-        "const": true,
-        "type": "boolean"
-      },
-      "imdb_id": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "imdb_rating": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "imdb_votes": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "metascore": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "rated": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "ratings": {
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "source": {
-              "type": "string"
-            },
-            "value": {
-              "type": "string"
-            }
-          },
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "rotten_tomatoes": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "runtime": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "title": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "year": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      }
-    },
-    "required": [
-      "found",
-      "imdb_id",
-      "title",
-      "year",
-      "rated",
-      "runtime",
-      "imdb_rating",
-      "imdb_votes",
-      "metascore",
-      "rotten_tomatoes",
-      "awards",
-      "ratings"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "found": {
+        "const": false,
+        "type": "boolean"
+      },
+      "reason": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "found",
+      "reason"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "awards": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "found": {
+        "const": true,
+        "type": "boolean"
+      },
+      "imdb_id": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "imdb_rating": {
+        "description": "IMDb user score, 0-10, as a string, e.g. '6.5'. Not TMDB's `vote_average`.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "imdb_votes": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "metascore": {
+        "description": "Metacritic critic score, 0-100 scale, as a string, e.g. '67'.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "rated": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "ratings": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "source": {
+              "type": "string"
+            },
+            "value": {
+              "type": "string"
+            }
+          },
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "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"
+        ]
+      },
+      "runtime": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "title": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "year": {
+        "type": [
+          "string",
+          "null"
+        ]
+      }
+    },
+    "required": [
+      "found",
+      "imdb_id",
+      "title",
+      "year",
+      "rated",
+      "runtime",
+      "imdb_rating",
+      "imdb_votes",
+      "metascore",
+      "rotten_tomatoes",
+      "awards",
+      "ratings"
+    ],
+    "type": "object"
+  }
+]

Changed1 schema field changedv0.10.1Jul 30, 2026

addedInput schema / properties / type

Added value: +{
+  "description": "Restrict a title lookup to this entry type. Verified live: without it, OMDb's own title match can silently prefer one type over another when the exact same title exists as more than one — e.g. a title lookup for 'Chuck' with no `type` returns the 2007 TV series, not the unrelated 2016 movie of the same name, with no signal the movie was ever in contention. Only affects a title lookup; has no effect when imdb_id is given (already unambiguous).",
+  "enum": [
+    "movie",
+    "series",
+    "episode"
+  ],
+  "type": "string"
+}

Addedv0.8.1Jul 26, 2026
Removedv0.8.0Jul 22, 2026
First observedv0.3.0Jul 9, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only say read-only and open-world; the description adds the real behavioral load: the API key requirement, that a no-match returns `{found:false, reason}` rather than an error, that the title path silently resolves to one arbitrary OMDb entry with no runner-up and no validation, and a concrete verified Halloween example showing a wrong-work risk. It even prescribes the mitigation (read back returned imdb_id/title/year).

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 it returns, then routing, then failure and ambiguity caveats — a sensible order with no filler sentences. It is dense and slightly overlong as a single paragraph, and the Halloween anecdote plus the repeated 'always read back / pass year' advice partly restate each other.

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 an output schema present, return values needn't be spelled out, yet the description still covers the one non-obvious return case (`found:false`) and the awards-summary shape. Combined with the annotations and schema, an agent has everything needed to call it correctly and interpret a suspicious 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% and the schema itself already documents precedence and the type/year disambiguation with examples, so the description is not carrying the full burden. It still adds operational guidance beyond the schema: 'imdb_id preferred', 'always pass year (and type) whenever you know them', and that type/ year only matter on the title path.

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 plus the exact resources it returns: IMDb/Rotten Tomatoes/Metacritic ratings, an awards summary (explicitly free-text, whole-title or single-episode, never a person), and OMDb's `rated` age rating. It also names its data source (OMDb) and its two lookup keys, so an agent can immediately distinguish it from get_movie/get_tv and find_by_imdb_id.

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 rules: prefer get_movie/get_tv when holding a TMDB id because they already include this data, and prefer search_movies/search_tv → get_movie/get_tv for title-only queries because that path validates against TMDB's year. It also states the precondition (OMDB_API_KEY) and the argument rule (one of imdb_id or title required; pass year/type when known).

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