MDBList MCP Server
This MCP server connects AI assistants to MDBList so they can search movies/TV, compare ratings and streaming data, and manage a user's lists, watchlist, history, ratings, favorites, and profile.
Search and discover movies/shows by title, genre, year, runtime, country, language, score, and sorting.
Get full media details, batch ratings from IMDb/Rotten Tomatoes/Metacritic/Letterboxd/TMDb/Trakt and others, streaming provider links, and similar titles.
Browse and search public, curated, official, liked, and external MDBList lists; inspect list metadata, items, and membership.
Create, edit, and delete personal lists; add or remove list items.
View, add to, and remove from the user's watchlist.
View watch history, collection, dropped items, last activity, item state, up-next episodes, and watch statistics.
Rate movies/shows, remove ratings, mark watched, and unmark watched.
Look up actors/directors, view favorite people and upcoming releases, and add or remove favorites.
View user profiles, supporter status, API limits, and public profiles.
Pulls IMDb ratings and scores for movies and TV shows into MDBList's combined rating data, retrievable via media info and batch rating lookups.
Retrieves Letterboxd ratings for movies and shows, allowing side-by-side comparison of scores across rating sources.
Supplies Metacritic scores for titles so they can be compared against other rating sources and used as catalog filter/sort criteria.
Provides MyAnimeList ratings and anime-specific genres for anime titles in search, discovery, and rating lookups.
Provides Rotten Tomatoes critics and audience scores for movies and shows, usable for filtering and sorting catalog discovery results.
Uses Trakt ratings and Trakt-linked data such as imported lists and watch history sync for movies and TV shows.
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., "@MDBList MCP Server Where can I stream Severance?"
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.
MDBList MCP Server
Connect Claude, Cursor and other AI assistants to MDBList. Search movies and TV shows, compare ratings from IMDb, Rotten Tomatoes, Metacritic, Letterboxd, TMDb and Trakt, and manage your lists, watchlist and watch history by just asking.
mdblist-mcp is a Model Context Protocol
(MCP) server. Once it's installed, your AI assistant can call the MDBList API
for you. You don't need to write any code.
What you can ask
"What are the top-rated sci-fi movies from 2025, sorted by Rotten Tomatoes score?"
"Compare the IMDb, Metacritic and Letterboxd ratings for Dune: Part Two."
"Where can I stream Severance?"
"Add the top 5 movies from that list to my 'Weekend' list."
"Which episodes are up next for the shows I'm watching?"
"Mark The Bear as watched and rate it 9/10."
"Find me something similar to Arrival."
"Which of my favourite actors have new movies coming out?"
Related MCP server: TorrentClaw-MCP
Features
Search and discovery: search by title, or browse the full movie and TV catalog filtered by genre, year, runtime, country, language and score.
Ratings from everywhere: IMDb, Rotten Tomatoes (critics and audience), Metacritic, Letterboxd, TMDb, Trakt, RogerEbert.com and MyAnimeList, plus MDBList's combined score. Batch lookups cover many titles at once.
Streaming availability: see where a movie or show is streaming.
Recommendations: get similar titles for any movie or show.
Lists: browse top, curated and official MDBList lists, search public lists, and create, fill, edit or delete your own.
Watchlist: view it, add to it, and remove from it.
Watch history and ratings: mark items as watched, rate titles, check what's up next or airing soon, and view your watch statistics.
People: look up actors and directors, follow your favourites and see their upcoming releases.
Quick start
1. Get a free MDBList API key
Sign in at mdblist.com, open Preferences, scroll to the API Access section and generate an API key (or copy your existing one). A free account works. Supporter accounts get higher rate limits and larger batch lookups.
2. Add the server to your AI client
You need Docker. Your client starts the
published image (ghcr.io/j1lt3d/mdblist-mcp, linux/amd64 and
linux/arm64) when it needs it, so there's nothing else to install. To skip
Docker and run it with Node.js instead, see
Alternative: Node.js.
Claude Desktop
Open Settings → Developer → Edit Config, or edit the config file directly:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
Add this, then restart Claude Desktop:
{
"mcpServers": {
"mdblist": {
"command": "docker",
"args": ["run", "-i", "--rm", "-e", "MDBLIST_API_KEY", "ghcr.io/j1lt3d/mdblist-mcp"],
"env": { "MDBLIST_API_KEY": "your-api-key" }
}
}
}Claude Code
claude mcp add mdblist -e MDBLIST_API_KEY=your-api-key -- docker run -i --rm -e MDBLIST_API_KEY ghcr.io/j1lt3d/mdblist-mcpCursor, Windsurf, Cline and other MCP clients
Any client that supports stdio MCP servers can use the same mcpServers block
as Claude Desktop. In Cursor, add it to ~/.cursor/mcp.json (global) or
.cursor/mcp.json (per project).
VS Code (GitHub Copilot)
Add to .vscode/mcp.json:
{
"servers": {
"mdblist": {
"command": "docker",
"args": ["run", "-i", "--rm", "-e", "MDBLIST_API_KEY", "ghcr.io/j1lt3d/mdblist-mcp"],
"env": { "MDBLIST_API_KEY": "your-api-key" }
}
}
}3. Ask away
Try "What's on my MDBList watchlist?" to check that it works.
Updating and pinning
Tags: latest, X.Y.Z and X.Y. To update, run
docker pull ghcr.io/j1lt3d/mdblist-mcp and restart your client. To pin a
version, use a tag such as ghcr.io/j1lt3d/mdblist-mcp:0.2.0 in the config.
The container runs as an unprivileged user, and its application files are read-only.
Alternative: Node.js
To run the server without Docker, you need Node.js 22 or newer and Git:
git clone https://github.com/j1lt3d/mdblist-mcp.git
cd mdblist-mcp
npm ci
npm run buildThis builds the server into dist/index.js. In your client config, use node
with the path to that file instead of docker (run pwd inside the folder to
see its absolute path):
{
"mcpServers": {
"mdblist": {
"command": "node",
"args": ["/absolute/path/to/mdblist-mcp/dist/index.js"],
"env": { "MDBLIST_API_KEY": "your-api-key" }
}
}
}For Claude Code:
claude mcp add mdblist -e MDBLIST_API_KEY=your-api-key -- node /absolute/path/to/mdblist-mcp/dist/index.jsTo update later, run git pull && npm ci && npm run build in the same folder.
To build the Docker image yourself instead, run docker build -t mdblist-mcp .
there.
Coming soon: once
mdblist-mcpis published to npm, you'll be able to run it withnpx -y mdblist-mcpwithout cloning.
Alternative: Streamable HTTP
To run the server as a long-lived network service (for example on a home
server shared by several clients), set MCP_TRANSPORT=http:
docker run -d --name mdblist-mcp -p 3000:3000 \
-e MDBLIST_API_KEY=your-api-key \
-e MCP_TRANSPORT=http \
-e MCP_AUTH_TOKEN=a-long-random-secret \
ghcr.io/j1lt3d/mdblist-mcpClients then connect to http://your-host:3000/mcp and send the token as a
bearer token. For example, in Claude Code:
claude mcp add --transport http mdblist http://your-host:3000/mcp \
--header "Authorization: Bearer a-long-random-secret"Requests from browsers are only accepted from localhost pages by default. To
use a browser-based client served from another host, list its hostname in
MCP_ALLOWED_ORIGINS (for example mdblist.lan). Other clients don't send an
Origin header and aren't affected.
GET /healthz returns 200 ok without authentication, for container health
checks. With the Node.js build, run
MCP_TRANSPORT=http MDBLIST_API_KEY=… node dist/index.js, which listens on
127.0.0.1:3000 by default.
Every HTTP client shares your MDBList API key, including tools that change
your lists, ratings and watch history. Always setMCP_AUTH_TOKEN when the
port is reachable by anyone else, and put the server behind HTTPS (a reverse
proxy) if it leaves your local network.
Available tools
The server has 33 tools, grouped by area. Tools marked ✏️ change your MDBList
data, and 🗑️ marks removals. Every tool carries MCP annotations (readOnlyHint,
destructiveHint), so clients can ask you to confirm before a change.
Tool | What it does |
| Search movies and shows by title |
| Full details for a title: ratings, scores, streaming services, IDs and optional similar titles |
| One rating source (IMDb, Rotten Tomatoes, Letterboxd, …) for many titles at once |
| Browse the catalog with filters (genre, year, score, runtime, country, language) and sorting |
| List available genres, including anime genres |
| Direct watch-provider links (supporter feature) |
Tool | What it does |
| Your MDBList lists, or another user's public lists |
| Top, curated, liked, official, or your imported IMDb/Trakt/Letterboxd lists |
| Search public lists by title |
| List details: name, owner, item count, likes |
| Movies and shows in a list, with filtering, sorting and pagination |
| Which of your lists already contain a title |
| Create a new list |
| Add titles to one of your lists |
| Remove titles from one of your lists |
| Permanently delete one of your lists |
Tool | What it does |
| Your watchlist |
| Add titles to your watchlist |
| Remove titles from your watchlist |
Tool | What it does |
| Your watched history, ratings, collection, or dropped shows and seasons |
| When your watched items, ratings and other data last changed |
| Watched, rated, collected and watchlist state for up to 100 titles |
| Next episodes for shows in progress, upcoming episodes, and watchlisted shows |
| Rate movies and shows |
| Remove your ratings |
| Mark movies or whole shows as watched |
| Remove watched status |
Tool | What it does |
| Details on an actor, director or other crew member |
| Your favourite people, or their upcoming movies and episodes |
| Add a person to your favourites |
| Remove a person from your favourites |
Tool | What it does |
| Your profile, supporter status and API limits, or another user's profile |
| Your watch statistics |
Results are MDBList's own JSON, sent in compact form. Related endpoints share one tool, which keeps the tool list at about 7k tokens of your assistant's context. Scrobbling, check-ins, discussions, notifications, devices and account management are left out on purpose.
Configuration
Environment variable | Required | Description |
| Yes | Your API key from mdblist.com/preferences |
| No |
|
| No | HTTP bind address. Defaults to |
| No | HTTP port. Defaults to |
| No | If set, HTTP clients must send |
| No | Comma-separated hostnames (no scheme or port; IPv6 in brackets) that browser-based clients may connect from, in addition to localhost |
The HTTP settings are only read when MCP_TRANSPORT=http.
The server communicates over stdio by default, or Streamable HTTP at /mcp
when MCP_TRANSPORT=http. It only contacts api.mdblist.com, and doesn't collect any data or send it anywhere else. API errors, including rate
limits (429 with Retry-After), are passed back to the assistant so it can
explain them or try again.
FAQ
What is MDBList?
MDBList is a free service that combines movie and TV ratings from many sources and lets you build lists, including dynamic lists you can use in Radarr and Sonarr. It also tracks your watchlist and watch history.
What is an MCP server?
The Model Context Protocol is an open standard for connecting AI assistants to tools and data. An MCP server like this one gives the assistant a set of actions it can perform, in this case calls to the MDBList API.
Which AI apps does it work with?
Any MCP client that supports local (stdio) or Streamable HTTP servers. That includes Claude Desktop, Claude Code, Cursor, Windsurf, Cline, VS Code with GitHub Copilot, and others. It supports MCP specification 2026-07-28, and older 2025 clients still work.
Do I need an MDBList supporter account?
No. A free account works with almost every tool. Supporters get higher API rate
limits and larger batch lookups: get_ratings accepts 100 IDs per call instead
of 10. get_watch_providers is a supporter feature, but get_media_info also
lists streaming services for everyone.
The server doesn't show up in Claude Desktop
Restart Claude Desktop completely after you edit the config.
With Docker: check that Docker is running (
docker info) and thatdocker pull ghcr.io/j1lt3d/mdblist-mcpworks. If the client can't finddocker, use its full path fromwhich dockeras thecommand.With Node.js: check that
node --versionprints 22 or higher.Check that the config file is valid JSON and that
MDBLIST_API_KEYis set.Look at the MCP logs (Settings → Developer) for error messages.
Can it change or delete my data?
Only through the ✏️ and 🗑️ tools listed above, and only when you ask. Clients that respect MCP annotations ask you to confirm before a destructive action.
Development
git clone https://github.com/j1lt3d/mdblist-mcp.git
cd mdblist-mcp
npm ci
npm run build
MDBLIST_API_KEY=... node dist/index.jsCommand | Purpose |
| Run from source with |
| ESLint (strict, type-checked) |
|
|
| Prettier |
| Vitest |
| Vitest with v8 coverage (≥ 90% enforced) |
Tools are declared as data in src/tools/<domain>.ts, using shared schemas
from src/tools/shared.ts. One generic handler in src/server.ts serves all
of them through MdblistClient. To add an endpoint, add a defineTool entry
and a request test case in test/tools/<domain>.test.ts.
CI checks formatting, lint, types, tests with coverage, the build, npm audit,
npm signature verification and the Dockerfile (hadolint).
Releases are automated with
semantic-release. PR
titles must follow Conventional Commits
(feat:, fix:, …), since squash-merged titles decide the next version. Each
release on main updates CHANGELOG.md, tags vX.Y.Z, creates a GitHub
release, and pushes the image to ghcr.io/j1lt3d/mdblist-mcp.
Contributions are welcome. Please open an issue or pull request.
License
This project was built with AI assistance (Claude Code). It has an automated test suite, but please report anything that looks wrong.
This is an unofficial project and isn't affiliated with or endorsed by MDBList. Movie and TV data is provided by the MDBList API.
Available Tools
33 toolsadd_list_itemsAdd list itemsBIdempotent
Add movies/shows to one of the user's static lists.
Inputs: list_id (required), shows, movies.
add_watchlist_itemsAdd to watchlistCIdempotent
Add movies/shows to the user's watchlist.
Inputs: shows, movies.
browse_listsBrowse listsARead-only
Browse lists: top public lists, curated lists, your liked lists, official MDBList lists, or your connected external lists. External lists are returned with external_id: pass it to get_list/get_list_items as list: {external_id}.
Inputs: source (required), limit, offset.
create_listCreate listC
Create a new static list for the user.
Inputs: name (required), private.
delete_listDelete listADestructiveIdempotent
Permanently delete one of the user's static lists (dynamic, official and external lists cannot be deleted).
Inputs: list_id (required).
discover_catalogDiscover catalogCRead-only
Browse the movie or show catalog with filters and sorting.
Inputs: media_type (required), sort, genre, limit, +14 more.
favorite_personFavorite personBIdempotent
Add a person to the user's favorites (subject to a tier-based limit).
Inputs: tmdb_id (required), role.
get_favorite_peopleGet favorite peopleARead-only
Get the user's favorited people, or (upcoming=true) upcoming movies/episodes featuring them.
Inputs: limit, offset, upcoming.
get_genresGet genresARead-only
List available genres (use the slugs to filter catalogs and lists).
Inputs: anime.
get_item_stateGet item stateARead-only
Get watched, rated, collected and watchlist state for up to 100 movies, shows or episodes.
Inputs: ids (required), provider (required), media_type (required).
get_last_activitiesGet last activitiesBRead-only
Get timestamps of when the user last changed watched items, ratings and other sync data.
Inputs: no named parameters.
get_listGet listBRead-only
Get metadata (name, owner, item count, likes) of a list.
Inputs: list (required).
get_list_itemsGet list itemsARead-only
Get the movies and shows in a list, with filtering, sorting and pagination.
Inputs: list (required), sort, limit, order, +6 more.
get_list_membershipGet list membershipBRead-only
Find which of the user's static lists contain a movie, show, season or episode.
Inputs: mediatype (required), imdb, tmdb, tvdb, +2 more.
get_media_infoGet media infoARead-only
Get full details (ratings, scores, streams, IDs) for a movie or show by provider ID. Also finds similar titles: append "recommendations" for up to ~8 related movies/shows (sparse for niche titles).
Inputs: id (required), provider (required), media_type (required), append_to_response.
get_personGet personARead-only
Get details of a person (actor, director, …) by TMDb person ID.
Inputs: tmdb_id (required).
get_ratingsGet ratings (batch)ARead-only
Get one rating source for many movies or shows at once. Max 10 IDs per call (100 for supporters).
Inputs: ids (required), media_type (required), rating_source (required), provider.
get_syncGet sync snapshotBRead-only
Get the user's watched history, ratings, collection, dropped shows or dropped seasons.
Inputs: kind (required), tmdb, limit, since, +2 more.
get_up_nextGet up nextARead-only
Get next episodes: next (in-progress shows), upcoming (caught-up shows airing soon), upcoming_episodes (every followed show) or watchlist (watchlisted shows).
Inputs: days, view, limit, offset, +1 more.
get_userGet userARead-only
Get the authenticated user's profile, supporter status and API rate limits, or another user's public profile.
Inputs: username.
get_user_listsGet user listsARead-only
List the authenticated user's MDBList-made lists, or another user's public lists. Excludes lists imported from IMDb, Trakt or Letterboxd: use browse_lists with source 'external' for those.
Inputs: sort, unified, username.
get_user_statsGet user statsARead-only
Get the authenticated user's precalculated watch statistics.
Inputs: no named parameters.
get_watchlistGet watchlistBRead-only
Get the authenticated user's watchlist items.
Inputs: sort, limit, order, cursor, +5 more.
get_watch_providersGet watch provider linksARead-only
Get direct streaming/watch-provider links for a movie or show (supporter feature; empty for others). May be rejected for API-key access; get_media_info also lists providers.
Inputs: id (required), provider (required), media_type (required).
mark_watchedMark watchedB
Mark movies or whole shows as watched for the user.
Inputs: shows, movies.
rate_mediaRate mediaBIdempotent
Add or update the user ratings of movies/shows.
Inputs: shows, movies.
remove_list_itemsRemove list itemsBDestructiveIdempotent
Remove movies/shows from one of the user's static lists.
Inputs: list_id (required), shows, movies.
remove_ratingsRemove ratingsADestructiveIdempotent
Remove the user ratings of movies/shows (watched status is kept).
Inputs: shows, movies.
remove_watchlist_itemsRemove from watchlistBDestructiveIdempotent
Remove movies/shows from the user's watchlist.
Inputs: shows, movies.
search_listsSearch listsBRead-only
Search public lists by title.
Inputs: query (required), limit, offset.
search_mediaSearch mediaCRead-only
Search movies and shows by title.
Inputs: query (required), year, limit, media_type, +2 more.
unfavorite_personUnfavorite personCDestructiveIdempotent
Remove a person from the user's favorites.
Inputs: tmdb_id (required).
unmark_watchedUnmark watchedADestructiveIdempotent
Remove the watched status of movies or whole shows (ratings are kept).
Inputs: shows, movies.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 33 tools
Most tools are cleanly separated by resource and action: watchlist, static lists, sync/history, ratings, media lookup, people, and user profile are distinct areas. Some overlap remains between list discovery tools (get_user_lists, browse_lists, search_lists) and between get_ratings versus user-rating tools, but descriptions generally clarify the boundaries.
Tool names consistently use snake_case verb_noun phrasing such as get_*, add_*, remove_*, create_*, delete_*, favorite_*, and unmark_*. Singular/plural variation follows the resource being addressed and remains predictable.
With 33 tools, the surface is heavy for a single MCP server and exceeds the typical well-scoped range. While MDBList is a broad domain, several areas could be consolidated, and the large count increases agent selection burden.
Coverage is strong across media search and details, lists, watchlist, ratings, sync/history, people, and user profiles. Minor gaps include editing list metadata (rename/description) and explicit like/unlike list operations, plus no people search by name.
Maintenance
Related MCP Connectors
Track the TV and films you watch, and find more like them, by talking to your own AI.
The media memory layer for AI agents and their humans. Your AI client can search your collection, add and log what you've finished, update ratings and lists, and find patterns across everything you've read, watched, played, and listened to.
Film and TV knowledge: character relationship maps, watch orders, cast and universes.
Rights-aware documentary search, film details, and where-to-watch for AI assistants. 100,000+ films.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides integration with The Movie Database (TMDB) API for searching movies, TV shows, and people, accessing detailed information, and discovering popular and trending content. Enables AI assistants to access comprehensive movie and television metadata including ratings, cast, crew, and overviews.1ISC

TorrentClaw-MCPofficial
AlicenseAqualityCmaintenanceGiving AI assistants the ability to search movies and TV shows, find torrents with magnet links, check streaming availability, and explore cast/crew metadata.521052 npm18MIT- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to manage media automation services like Sonarr, Radarr, Prowlarr, Bazarr, Overseerr, and Plex through natural language commands.9MIT
- FlicenseAqualityDmaintenanceEnables searching for movies and TV shows and retrieving streaming availability data across multiple platforms and countries.33-