Skip to main content
Glama
MDBList MCP Server

MDBList MCP Server

by j1lt3d

MDBList MCP Server

License: MIT Node.js ≥ 22 MCP 2026-07-28

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.json

  • Windows: %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-mcp

Cursor, 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 build

This 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.js

To 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-mcp is published to npm, you'll be able to run it with npx -y mdblist-mcp without 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-mcp

Clients 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.

WARNING

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_media

Search movies and shows by title

get_media_info

Full details for a title: ratings, scores, streaming services, IDs and optional similar titles

get_ratings

One rating source (IMDb, Rotten Tomatoes, Letterboxd, …) for many titles at once

discover_catalog

Browse the catalog with filters (genre, year, score, runtime, country, language) and sorting

get_genres

List available genres, including anime genres

get_watch_providers

Direct watch-provider links (supporter feature)

Tool

What it does

get_user_lists

Your MDBList lists, or another user's public lists

browse_lists

Top, curated, liked, official, or your imported IMDb/Trakt/Letterboxd lists

search_lists

Search public lists by title

get_list

List details: name, owner, item count, likes

get_list_items

Movies and shows in a list, with filtering, sorting and pagination

get_list_membership

Which of your lists already contain a title

create_list ✏️

Create a new list

add_list_items ✏️

Add titles to one of your lists

remove_list_items 🗑️

Remove titles from one of your lists

delete_list 🗑️

Permanently delete one of your lists

Tool

What it does

get_watchlist

Your watchlist

add_watchlist_items ✏️

Add titles to your watchlist

remove_watchlist_items 🗑️

Remove titles from your watchlist

Tool

What it does

get_sync

Your watched history, ratings, collection, or dropped shows and seasons

get_last_activities

When your watched items, ratings and other data last changed

get_item_state

Watched, rated, collected and watchlist state for up to 100 titles

get_up_next

Next episodes for shows in progress, upcoming episodes, and watchlisted shows

rate_media ✏️

Rate movies and shows

remove_ratings 🗑️

Remove your ratings

mark_watched ✏️

Mark movies or whole shows as watched

unmark_watched 🗑️

Remove watched status

Tool

What it does

get_person

Details on an actor, director or other crew member

get_favorite_people

Your favourite people, or their upcoming movies and episodes

favorite_person ✏️

Add a person to your favourites

unfavorite_person 🗑️

Remove a person from your favourites

Tool

What it does

get_user

Your profile, supporter status and API limits, or another user's profile

get_user_stats

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

MDBLIST_API_KEY

Yes

Your API key from mdblist.com/preferences

MCP_TRANSPORT

No

stdio (default) or http

MCP_HOST

No

HTTP bind address. Defaults to 127.0.0.1 (0.0.0.0 in the Docker image)

PORT

No

HTTP port. Defaults to 3000

MCP_AUTH_TOKEN

No

If set, HTTP clients must send Authorization: Bearer <token>

MCP_ALLOWED_ORIGINS

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 that docker pull ghcr.io/j1lt3d/mdblist-mcp works. If the client can't find docker, use its full path from which docker as the command.

  • With Node.js: check that node --version prints 22 or higher.

  • Check that the config file is valid JSON and that MDBLIST_API_KEY is 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.js

Command

Purpose

npm run dev

Run from source with tsx

npm run lint

ESLint (strict, type-checked)

npm run typecheck

tsc --noEmit

npm run format:check

Prettier

npm test

Vitest

npm run test:coverage

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

MIT

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 tools
add_list_itemsAdd list itemsB
Idempotent

Add movies/shows to one of the user's static lists.

Inputs: list_id (required), shows, movies.

add_watchlist_itemsAdd to watchlistC
Idempotent

Add movies/shows to the user's watchlist.

Inputs: shows, movies.

browse_listsBrowse listsA
Read-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 listA
DestructiveIdempotent

Permanently delete one of the user's static lists (dynamic, official and external lists cannot be deleted).

Inputs: list_id (required).

discover_catalogDiscover catalogC
Read-only

Browse the movie or show catalog with filters and sorting.

Inputs: media_type (required), sort, genre, limit, +14 more.

favorite_personFavorite personB
Idempotent

Add a person to the user's favorites (subject to a tier-based limit).

Inputs: tmdb_id (required), role.

get_favorite_peopleGet favorite peopleA
Read-only

Get the user's favorited people, or (upcoming=true) upcoming movies/episodes featuring them.

Inputs: limit, offset, upcoming.

get_genresGet genresA
Read-only

List available genres (use the slugs to filter catalogs and lists).

Inputs: anime.

get_item_stateGet item stateA
Read-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 activitiesB
Read-only

Get timestamps of when the user last changed watched items, ratings and other sync data.

Inputs: no named parameters.

get_listGet listB
Read-only

Get metadata (name, owner, item count, likes) of a list.

Inputs: list (required).

get_list_itemsGet list itemsA
Read-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 membershipB
Read-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 infoA
Read-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 personA
Read-only

Get details of a person (actor, director, …) by TMDb person ID.

Inputs: tmdb_id (required).

get_ratingsGet ratings (batch)A
Read-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 snapshotB
Read-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 nextA
Read-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 userA
Read-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 listsA
Read-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 statsA
Read-only

Get the authenticated user's precalculated watch statistics.

Inputs: no named parameters.

get_watchlistGet watchlistB
Read-only

Get the authenticated user's watchlist items.

Inputs: sort, limit, order, cursor, +5 more.

get_watch_providersGet watch provider linksA
Read-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 mediaB
Idempotent

Add or update the user ratings of movies/shows.

Inputs: shows, movies.

remove_list_itemsRemove list itemsB
DestructiveIdempotent

Remove movies/shows from one of the user's static lists.

Inputs: list_id (required), shows, movies.

remove_ratingsRemove ratingsA
DestructiveIdempotent

Remove the user ratings of movies/shows (watched status is kept).

Inputs: shows, movies.

remove_watchlist_itemsRemove from watchlistB
DestructiveIdempotent

Remove movies/shows from the user's watchlist.

Inputs: shows, movies.

search_listsSearch listsB
Read-only

Search public lists by title.

Inputs: query (required), limit, offset.

search_mediaSearch mediaC
Read-only

Search movies and shows by title.

Inputs: query (required), year, limit, media_type, +2 more.

unfavorite_personUnfavorite personC
DestructiveIdempotent

Remove a person from the user's favorites.

Inputs: tmdb_id (required).

unmark_watchedUnmark watchedA
DestructiveIdempotent

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

    B3.3/5.0

    Scored across 33 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides 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.
      1
      ISC
    • A
      license
      A
      quality
      C
      maintenance
      Giving AI assistants the ability to search movies and TV shows, find torrents with magnet links, check streaming availability, and explore cast/crew metadata.
      52
      10
      52 npm
      18
      MIT