Skip to main content
Glama
TMDB MCP Server

TMDB MCP Server

Get IMDb/RT/Metacritic ratings

get_ratings
Read-only

Look up IMDb, Rotten Tomatoes, and Metacritic ratings, awards summaries, and OMDb age ratings by IMDb ID or title with optional year/type to confirm the exact film, show, or episode.

Instructions

Look up IMDb, Rotten Tomatoes and Metacritic ratings, an awards summary and OMDb's own age rating (rated) from OMDb, by IMDb id (preferred, e.g. 'tt0133093') or by title (+ optional year/type). The awards summary is free text (major-award wins/nominations: Oscars, Emmys, Golden Globes, etc.), not a structured count, and covers the whole film/show, or one episode when given an episode's imdb_id, never one person. 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 refusal (bad key, exhausted daily quota) is. A title lookup resolves to whichever single entry OMDb picks, reports no runner-up, and cannot be validated, so it can silently return a different work of the same name. Checked 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 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: that path matches by imdb_id and also drops an OMDb hit whose release year is more than two years from TMDB's, which this tool's title path cannot do.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "get_ratings"
  }
}

Input Schema

NameRequiredDescriptionDefault
typeNoRestrict a title lookup to this entry type. Checked live: without it, OMDb's title match can silently prefer one type when the same title exists as more than one, e.g. a 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. Affects only a title lookup; no effect when imdb_id is given (already unambiguous).
yearNoYear, to disambiguate a title.
titleNoMovie/show title (used when imdb_id is absent).
imdb_idNoIMDb title id. Takes precedence over title when both are given.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.15.0
    • changedInput schema / properties / type / description
      Previous value: -"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)."New value: +"Restrict a title lookup to this entry type. Checked live: without it, OMDb's title match can silently prefer one type when the same title exists as more than one, e.g. a 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. Affects only a title lookup; no effect when imdb_id is given (already unambiguous)."
  2. Changed1 schema field changedv0.14.0
    • 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"
      +  }
      +]
  3. Changed1 schema field changedv0.10.1
    • 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"
      +}
  4. Addedv0.8.1
  5. Removedv0.8.0
  6. First observedv0.3.0

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare readOnlyHint and openWorldHint, but the description adds substantial context: no-match returns {found:false, reason} versus a refusal being an error, and it discloses that title lookups can silently resolve to a different same-named work with no runner-up. The Halloween example makes the failure mode concrete, and the instruction to read back imdb_id/title/year is actionable behavioral guidance.

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-loads the purpose, then layers behavioral caveats and routing guidance logically. It is long, and the multi-sentence Halloween walkthrough is the most verbose section, but the density earns most of its space. Slightly trimmable, hence not a 5.

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, so return-value explanation is not owed, and the description still clarifies the found:false shape and the free-text nature of the awards summary. For a read-only lookup of this complexity, nothing an agent needs to invoke it correctly or interpret ambiguity is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents all four parameters including precedence and the type-affects-title-only nuance. The description adds useful emphasis ('imdb_id preferred', 'pass year and type whenever you know them') but largely reinforces what the schema already states. Baseline 3 is appropriate when the schema does the heavy lifting.

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?

Opens with a specific verb+resource: 'Look up IMDb, Rotten Tomatoes and Metacritic ratings, an awards summary and OMDb's own age rating from OMDb.' It names the source (OMDb) and explicitly distinguishes itself from get_movie/get_tv, which already include this data. An agent can tell exactly what this tool returns versus its siblings.

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 guidance: prefer get_movie/get_tv when you have a TMDB id, and when you only have a title prefer search_movies/search_tv → get_movie/get_tv. It states the prerequisite (OMDB_API_KEY), the required-parameter rule (one of imdb_id or title), and when-not to use this tool. Nothing is left to inference.

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