IMDb MCP server
Provides tools for interacting with IMDb data, including searching titles and people, retrieving title details, credits, episodes, reviews, similar titles, box office, charts, upcoming releases, and advanced title search. It can also read a user's public IMDb ratings and watchlist, query rating history, and compare personal ratings with IMDb averages.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@IMDb MCP server what did I rate Alien?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
IMDb MCP server
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.
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 |
RapidAPI, 5 results a page | no | no | RapidAPI subscription | |
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 |
| Find a film, series, episode or person and get its id |
| One title in full: plot, ratings, cast and crew, release, certificate, awards, poster |
| The rest of a title page |
| A person and their filmography |
| Genre, type, years, rating, votes, keywords and sort, like imdb.com/search/title |
| Top 250, lowest rated, top TV, most popular |
| Upcoming films or series from a date |
| Your ratings a page at a time, newest or highest first |
| What you gave one title, if anything |
| Search the whole history: words, years, rating range, genre, type, date rated |
| Count, average, spread from 1 to 10, per year, decades, genres, difference to IMDb's averages |
| Your watchlist, or any public list by its |
| Who the server is reading, with ratings and watchlist counts |
| 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.xxxxIMDB_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-mcpHosting 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 |
| 8620 | The server. No login of its own, never exposed |
nginx | 8621 | Front door, behind a Cloudflare Tunnel |
| 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/envCopy 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 testsThe 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 toolsadvanced_title_searchARead-onlyIdempotent
Search titles by genre, type, year, rating, vote count and keywords.
This is IMDb's advanced search: "best rated horror films of the 1970s with over 10 000 votes" is one call.
Args: genres: Genre names as IMDb spells them: Horror, Sci-Fi, Film-Noir, Drama. title_types: Any of movie, tvSeries, tvMiniSeries, tvMovie, tvEpisode, short, video, videoGame. year_from: Earliest release year. year_to: Latest release year. min_rating: Lowest IMDb average, 1 to 10. max_rating: Highest IMDb average. min_votes: Fewest votes; 10000 keeps out the obscure. keywords: Plot keywords, all required, such as ["space", "alien"]. text: Words in the title. sort: popularity, rating, votes, release_date, alphabetical, runtime, metascore or box_office. order: ASC or DESC. limit: How many per page. cursor: next_cursor from the previous page.
Inputs: sort, text, limit, order, +9 more. Returns: result
find_my_ratingsARead-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_officeBRead-onlyIdempotent
Budget, opening weekend and lifetime grosses by area for a title.
Args: id: Title id.
Inputs: id (required). Returns: result
get_chartARead-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_soonARead-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_listBRead-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_nameARead-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_creditsARead-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_pageARead-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_titlesBRead-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_titleARead-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_creditsARead-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_episodesARead-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_reviewsARead-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_profileARead-onlyIdempotent
Who the configured user is on IMDb, with their ratings and watchlist counts.
Inputs: no named parameters. Returns: result
my_rating_forARead-onlyIdempotent
What the configured user rated one title, if anything.
Args: id: Title id, from search_titles.
Inputs: id (required). Returns: result
my_ratingsARead-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_statsARead-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_watchlistARead-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_namesARead-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_titlesARead-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
Scored across 21 tools
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.
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.
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.
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
Related MCP Connectors
YouTube transcripts, IMDb search and podcast search as agent tools.
Movie and series ranking as MCP tools: top titles, search, lookup by IMDb id. Free, no key.
OMDb MCP — IMDB-derived movie / TV / episode data (BYO key)
IMDB MCP — title metadata, ratings, episodes, and crew from IMDB's official non-commercial bulk…
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables 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.2ISC
- AlicenseNot gradedqualityDmaintenanceEnables LLMs to read, search, and manage emails via IMAP with secure, read-only access to email accounts.6MIT
- AlicenseAqualityCmaintenanceEnables 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.12MIT
- AlicenseAqualityCmaintenanceGives 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.754 npmMIT