Skip to main content
Glama
IMDb MCP server

IMDb MCP server

by rollecode

IMDb MCP server

Version Python IMDb Tools

Read IMDb from Claude.ai, Claude Desktop and Claude Code: titles, people, credits, episodes, reviews, box office, charts and advanced search, and on top of that your own ratings and watchlist. "What did I rate Alien", "my 10s from the 1990s", "how do my scores compare to IMDb's" are one call each, over the whole history. No API key and no login: it talks to the same GraphQL API imdb.com itself uses, which answers public data to anyone.

WARNING

Using this server with a paid AI service costs money. Tool definitions and results are billed as input tokens, and an agent can call tools repeatedly on its own. You are responsible for every charge, so set spending limits with your provider. The author accepts no liability for any costs. SeeDISCLAIMER.md.

Why not the other options

Server

Source

Your ratings

Watchlist

Key needed

uzaysozen/imdb-mcp-server

RapidAPI, 5 results a page

no

no

RapidAPI subscription

clsung/mcp-imdb

scraping

no

no

none

Cinemagoer based servers

scraping

no

no

none

This one

IMDb's own GraphQL API

whole history

yes

none

None of them know who you are. This one reads the ratings and watchlist that your IMDb profile shows publicly, which is where the questions worth asking live.

Related MCP server: mcp-imap-server

Tools

Tool

What it does

search_titles, search_names

Find a film, series, episode or person and get its id

get_title

One title in full: plot, ratings, cast and crew, release, certificate, awards, poster

get_title_credits, get_title_episodes, get_title_reviews, get_similar_titles, get_box_office

The rest of a title page

get_name, get_name_credits

A person and their filmography

advanced_title_search

Genre, type, years, rating, votes, keywords and sort, like imdb.com/search/title

get_chart

Top 250, lowest rated, top TV, most popular

get_coming_soon

Upcoming films or series from a date

my_ratings

Your ratings a page at a time, newest or highest first

my_rating_for

What you gave one title, if anything

find_my_ratings

Search the whole history: words, years, rating range, genre, type, date rated

my_rating_stats

Count, average, spread from 1 to 10, per year, decades, genres, difference to IMDb's averages

my_watchlist, get_list

Your watchlist, or any public list by its ls id

get_user_profile

Who the server is reading, with ratings and watchlist counts

get_result_page

The rest of an answer too large to send at once

The ratings history is fetched once, 250 at a time, and kept for 15 minutes, so a run of questions about it costs one round of requests.

Setup

git clone https://github.com/rollecode/imdb-mcp.git
cd imdb-mcp
uv venv && uv pip install -e .

Tell it who you are. Open your ratings page on imdb.com, https://www.imdb.com/user/p.xxxx/ratings/, and copy the p.xxxx part:

export IMDB_PROFILE_ID=p.xxxx

IMDB_USER_ID=ur12345678 works too if you know it. A .env in the working directory works as well. Your ratings and watchlist must be set public in your IMDb settings, since the server has no login; everything else needs nothing.

Claude Code

claude mcp add imdb -- /path/to/imdb-mcp/.venv/bin/imdb-mcp

Hosting it

Running it over HTTP puts it in reach of Claude.ai and Claude Desktop as a custom connector, and of Claude Code on other machines. Three tiers, the same shape the other servers in this family use:

Tier

Port

What it does

imdb-mcp

8620

The server. No login of its own, never exposed

nginx

8621

Front door, behind a Cloudflare Tunnel

auth-server.js

8622

OAuth 2.1 sign-in, or a fixed bearer token

npm install
node set-password.js 'a password for the sign-in page'
printf 'IMDB_PROFILE_ID=p.xxxx\n' > ~/.config/imdb-mcp/env
chmod 600 ~/.config/imdb-mcp/env

Copy systemd/*.service to /etc/systemd/system/, replacing YOUR_USER and the ISSUER, and systemd/imdb-mcp.nginx.conf to your nginx sites. Point a tunnel hostname at 127.0.0.1:8621. In Claude.ai: Settings, Connectors, Add custom connector, the URL https://your-host/mcp, client id and secret blank, then sign in with the password.

A fixed token in ~/.config/imdb-mcp/token is accepted as a bearer token too:

claude mcp add --transport http imdb https://your-host/mcp --header "Authorization: Bearer $(cat ~/.config/imdb-mcp/token)"

IMDb's terms

The API answers with a notice: public, commercial or non-private use of its data is not allowed, and limited non-commercial use is governed by IMDb's conditions. This server is for reading your own account and looking things up for yourself. Do not put it in front of other people or a product, and do not store or republish what it returns.

Information courtesy of IMDb (https://www.imdb.com). Used with permission.

Development

uv pip install -e . --group dev
.venv/bin/python -m pytest -q
.venv/bin/ruff check src tests

The tests run every tool against a fake IMDb and check the GraphQL each one builds, the shape it returns, and that the ratings history is fetched once.

Available Tools

21 tools
find_my_ratingsA
Read-onlyIdempotent

Search the configured user's whole ratings history.

Every filter is optional and they combine: "my 9s and 10s from the 1990s", "horror I rated below 4", "everything I rated in 2024".

Args: query: Words in the title. year: Release year. year_from: Earliest release year. year_to: Latest release year. rating: Exactly this rating, 1 to 10. min_rating: At least this rating. max_rating: At most this rating. genre: Genre name such as Horror or Comedy. title_type: movie, tvSeries, tvEpisode and so on. rated_from: Earliest date rated, YYYY-MM-DD. rated_to: Latest date rated, YYYY-MM-DD. sort: rated_on, my_rating, imdb_rating, year or title. order: DESC or ASC. limit: How many to return.

Inputs: sort, year, genre, limit, +10 more. Returns: result

get_box_officeB
Read-onlyIdempotent

Budget, opening weekend and lifetime grosses by area for a title.

Args: id: Title id.

Inputs: id (required). Returns: result

get_chartA
Read-onlyIdempotent

IMDb's charts: the Top 250, lowest rated, top TV, most popular.

Args: chart: top_rated_movies, lowest_rated_movies, top_rated_tv_shows, top_rated_english_movies, most_popular_movies or most_popular_tv_shows. limit: How many entries per page. cursor: next_cursor from the previous page.

Inputs: chart, limit, cursor. Returns: result

get_coming_soonA
Read-onlyIdempotent

Upcoming releases, soonest first.

Args: kind: movie or tv. from_date: YYYY-MM-DD. Defaults to today. limit: How many per page. cursor: next_cursor from the previous page.

Inputs: kind, limit, cursor, from_date. Returns: result

get_listB
Read-onlyIdempotent

Any public IMDb list by its ls id, titles or people.

Args: id: List id such as ls055592025, or a URL containing one. limit: How many per page. cursor: next_cursor from the previous page.

Inputs: id (required), limit, cursor. Returns: result

get_nameA
Read-onlyIdempotent

Get one person: biography, dates, professions, known-for titles.

Args: id: Name id such as nm0000244, or an IMDb URL containing one.

Inputs: id (required). Returns: result

get_name_creditsA
Read-onlyIdempotent

A person's filmography, newest first.

Args: id: Name id. category: One of actor, actress, director, writer, producer, composer, cinematographer, editor. Omit for everything. limit: How many credits per page. cursor: next_cursor from the previous page.

Inputs: id (required), limit, cursor, category. Returns: result

get_result_pageA
Read-onlyIdempotent

Read more of a result that was too large to return in one piece.

Any tool whose answer is too large returns its first page with a paging block. Pass that block's result_id here. Nothing is fetched again: the stored result is paged, filtered and narrowed.

Args: result_id: From the paging block of the earlier answer. offset: First item to return, usually the previous next_offset. limit: At most this many items. Fewer come back if they would not fit. fields: Only these keys of each item. Dots reach nested keys, such as "statistics.sizeOnDisk". The paging.fields list shows what exists. match: Keep only items whose field contains this text, ignoring case, for example {"title": "alien", "year": "1979"}. path: Which list to page when the result holds several, as named in paging.lists. Defaults to the largest.

Inputs: result_id (required), path, limit, match, +2 more. Returns: result

get_similar_titlesB
Read-onlyIdempotent

Titles IMDb lists as more like this one.

Args: id: Title id. limit: How many to return.

Inputs: id (required), limit. Returns: result

get_titleA
Read-onlyIdempotent

Get one title in full: plot, ratings, cast and crew, genres, release, certificate, awards, taglines and poster.

Args: id: Title id such as tt0078748, or an IMDb URL containing one.

Inputs: id (required). Returns: result

get_title_creditsA
Read-onlyIdempotent

List who worked on a title, with characters for the cast.

Args: id: Title id. category: One of director, writer, actor, actress, producer, composer, cinematographer, editor. Omit for everyone, cast first. limit: How many credits per page. cursor: next_cursor from the previous page.

Inputs: id (required), limit, cursor, category. Returns: result

get_title_episodesA
Read-onlyIdempotent

List a series' seasons and episodes with their ratings.

Args: id: The series' title id. season: Only this season. Omit for all, in order. limit: How many episodes per page. cursor: next_cursor from the previous page.

Inputs: id (required), limit, cursor, season. Returns: result

get_title_reviewsA
Read-onlyIdempotent

Read user reviews of a title, most helpful first.

Args: id: Title id. limit: How many reviews per page. cursor: next_cursor from the previous page.

Inputs: id (required), limit, cursor. Returns: result

get_user_profileA
Read-onlyIdempotent

Who the configured user is on IMDb, with their ratings and watchlist counts.

Inputs: no named parameters. Returns: result

my_rating_forA
Read-onlyIdempotent

What the configured user rated one title, if anything.

Args: id: Title id, from search_titles.

Inputs: id (required). Returns: result

my_ratingsA
Read-onlyIdempotent

The configured user's own ratings, one page at a time.

For questions over the whole history use find_my_ratings or my_rating_stats.

Args: sort: recent (by date rated) or top (by the rating given). order: DESC or ASC. limit: How many per page, at most 250. cursor: next_cursor from the previous page.

Inputs: sort, limit, order, cursor. Returns: result

my_rating_statsA
Read-onlyIdempotent

Numbers over the configured user's whole ratings history: how many, the average, the spread from 1 to 10, ratings per year, favourite genres and decades, and where they sit against IMDb's averages.

Inputs: no named parameters. Returns: result

my_watchlistA
Read-onlyIdempotent

Titles on the configured user's watchlist, in list order.

Args: limit: How many per page. cursor: next_cursor from the previous page.

Inputs: limit, cursor. Returns: result

search_namesA
Read-onlyIdempotent

Find people: actors, directors, writers and crew.

Args: query: Name, or part of one. limit: How many matches to return.

Inputs: query (required), limit. Returns: result

search_titlesA
Read-onlyIdempotent

Find films, series and episodes by name.

Start here to get the tt id every other title tool needs.

Args: query: Title, or part of one. title_type: any, movie or tv. limit: How many matches to return.

Inputs: query (required), limit, title_type. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 21 tools

    Disambiguation4/5

    Most tools target clearly distinct IMDb resources and actions, and the user-rating tools are well differentiated. Minor overlap exists between search_titles and advanced_title_search, and the dual pagination pattern (cursor per tool vs. get_result_page) may occasionally confuse an agent.

    Naming Consistency4/5

    The dominant pattern is verb_noun (get_title, search_names, get_name_credits) and is mostly predictable. Deviations such as my_ratings, my_watchlist, my_rating_for, and advanced_title_search are readable but slightly break the convention.

    Tool Count3/5

    At 21 tools this is a fairly large surface, sitting in the heavy 16–25 range. The tools are related and mostly earn their place, but the set is broad enough that scoping could be tighter.

    Completeness4/5

    The server covers title search/detail/credits/episodes/reviews/similar/box office, name search/detail/credits, charts, coming soon, user ratings/watchlist/profile, and public lists. Minor gaps remain around write operations such as setting ratings or managing a watchlist, and some specialized IMDb endpoints are not exposed.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables users to connect to their email inbox via IMAP to search, filter, and summarize emails based on criteria like subject, date, and sender. Supports marking emails as read and provides customizable email summarization with various prompt options.
      2
      ISC
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables LLMs to read, search, and manage emails via IMAP with secure, read-only access to email accounts.
      6
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables Claude to read, manage, and send email from any IMAP mailbox over plain IMAP and SMTP, including hosting-company and self-hosted mail servers. It provides tools for searching, reading, moving, deleting, and composing messages while built-in safety rules prevent unintended changes.
      12
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Gives AI assistants IMAP/SMTP access to a mailbox so they can search folders, read and reply to messages, send email, and mark or move messages. Works with Namecheap Private Email by default and with other mailboxes via configurable hosts.
      7
      54 npm
      MIT