Skip to main content
Glama
README.md
# tmdb-mcp

[![CI](https://github.com/matanbaruch/tmdb-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/matanbaruch/tmdb-mcp/actions/workflows/ci.yml)

An [MCP](https://modelcontextprotocol.io) server for [The Movie Database (TMDB)](https://www.themoviedb.org) with **read and write** tools: search, details, discover, trending and streaming availability, plus your own ratings, watchlist, favorites and lists.

- Built on the **MCP TypeScript SDK v2** (`@modelcontextprotocol/server`), served over **stdio**.
- Speaks the **2026-07-28** protocol revision and still serves 2025-era clients (`initialize` handshake) on the same binary.
- 30 tools with input validation (zod) and `readOnlyHint` / `destructiveHint` / `idempotentHint` annotations, so clients can auto-approve reads and confirm writes.

## Tools

### Catalog (read-only, API key only)

| Tool | What it does |
| --- | --- |
| `search` | Text search across movies, TV, people, collections, companies or keywords (`type=multi` by default) |
| `get_movie` | Movie details; `append` embeds credits, videos, images, recommendations, reviews, watch providers, release dates and more |
| `get_tv_show` | TV show details; `append` embeds aggregate credits, content ratings, recommendations and more |
| `get_tv_season` | One season with its episode list |
| `get_tv_episode` | One episode with guest stars and crew |
| `get_person` | Person details; `append` embeds movie, TV or combined credits |
| `get_collection` | A franchise and all of its movies |
| `get_trending` | Trending movies, shows or people for the day or week |
| `get_movie_list` | Popular, top rated, now playing or upcoming movies |
| `get_tv_list` | Popular, top rated, airing today or on the air TV shows |
| `discover_movies` | Filter movies by genre, cast, crew, company, keyword, dates, rating, runtime, streaming provider (any other TMDB discover parameter via `extra`) |
| `discover_tv` | Filter TV by genre, network, dates, status, type, rating, streaming provider |
| `get_genres` | Genre IDs for movies or TV |
| `find_by_external_id` | Look up by IMDb, TVDB, Wikidata or social IDs |
| `get_watch_providers` | Where to stream, rent or buy, for all countries or one `region` |
| `get_recommendations` | Recommended or similar movies and shows |

### Your account (needs account credentials)

| Tool | Kind | What it does |
| --- | --- | --- |
| `get_account` | read | Account ID, username, language and country |
| `get_account_states` | read | Whether a movie, show or episode is favorited, watchlisted or rated by you |
| `get_account_items` | read | Your favorites, watchlist or ratings for movies, TV or episodes |
| `get_account_lists` | read | Your custom lists |
| `get_list` | read | A list's items; pass `movie_id` to check membership |
| `rate` | write | Rate a movie, show or episode from 0.5 to 10 |
| `delete_rating` | write | Remove a rating |
| `set_favorite` | write | Add or remove a favorite |
| `set_watchlist` | write | Add or remove a watchlist item |
| `create_list` | write | Create a list |
| `add_to_list` | write | Add a movie to a list |
| `remove_from_list` | write | Remove a movie from a list |
| `clear_list` | write | Remove every item from a list |
| `delete_list` | write | Delete a list |

## Setup

### 1. Get TMDB credentials

1. Create a free account at [themoviedb.org](https://www.themoviedb.org/signup).
2. Request an API key at [Settings → API](https://www.themoviedb.org/settings/api). You get both an **API Key** and an **API Read Access Token**; either one works.
3. For the account tools, also provide your TMDB username and password, or a session ID (see [Account access](#account-access)).

### 2. Add the server to your MCP client

The server installs and builds straight from GitHub with `npx`, no npm publish needed.

**Claude Code**

```sh
claude mcp add tmdb \
  -e TMDB_API_KEY=your_api_key \
  -e TMDB_USERNAME=your_username \
  -e TMDB_PASSWORD=your_password \
  -- npx -y github:matanbaruch/tmdb-mcp
```

**Claude Desktop, Cursor and other JSON-configured clients**

```json
{
  "mcpServers": {
    "tmdb": {
      "command": "npx",
      "args": ["-y", "github:matanbaruch/tmdb-mcp"],
      "env": {
        "TMDB_API_KEY": "your_api_key",
        "TMDB_USERNAME": "your_username",
        "TMDB_PASSWORD": "your_password"
      }
    }
  }
}
```

**From a local checkout**

```sh
git clone https://github.com/matanbaruch/tmdb-mcp.git
cd tmdb-mcp
npm ci
```

Then point your client at `node /absolute/path/to/tmdb-mcp/dist/index.js`.

## Configuration

| Variable | Required | Description |
| --- | --- | --- |
| `TMDB_API_KEY` | one of these two | TMDB v3 API key, sent as the `api_key` query parameter |
| `TMDB_READ_ACCESS_TOKEN` | one of these two | TMDB API Read Access Token, sent as a Bearer header. Used instead of the API key when both are set |
| `TMDB_USERNAME` / `TMDB_PASSWORD` | for account tools | The server logs in on first use and keeps the session in memory |
| `TMDB_SESSION_ID` | for account tools | An existing v3 session ID, used instead of username and password |
| `TMDB_LANGUAGE` | no | Default response language, e.g. `en-US` (default), `fr-FR`, `he-IL`. Every read tool also takes a `language` argument |

Without account credentials the catalog tools work normally, and the account tools return an error explaining what to configure.

### Account access

Username and password are the simplest option. If you'd rather not store your password, create a session ID once and set `TMDB_SESSION_ID`:

```sh
curl -s "https://api.themoviedb.org/3/authentication/token/new?api_key=$TMDB_API_KEY"
```

Open `https://www.themoviedb.org/authenticate/<request_token>` in a browser and approve it, then exchange the token:

```sh
curl -s -X POST "https://api.themoviedb.org/3/authentication/session/new?api_key=$TMDB_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"request_token":"<request_token>"}'
```

TMDB sessions do not expire until you revoke them under Settings → Sessions.

## Images

Image fields such as `poster_path`, `backdrop_path`, `still_path` and `profile_path` are relative. Build URLs as `https://image.tmdb.org/t/p/{size}{path}`, with size `w185`, `w342`, `w500`, `w780` or `original`. The server sends this hint to clients in its instructions.

## Limitations

- Lists use the TMDB v3 list API, which holds **movies only**. Favorites, watchlist and ratings support both movies and TV.
- Episode favorites and watchlist entries do not exist on TMDB. Episodes can only be rated.

## Development

```sh
npm ci
npm run typecheck
npm test
```

`npm test` builds the server, then runs:

- **Unit tests** (`test/unit`): every tool against a mocked TMDB API, checking the HTTP method, path, query, body, session handling, validation and error mapping.
- **Stdio tests** (`test/stdio`): spawn the built server over stdio, negotiate both the 2026-07-28 and the 2025-11-25 protocol, and list and call tools.

### Live tests

`npm run test:live` drives every tool against the real TMDB API through the stdio server. It covers reads and full write round trips: rate, read back, delete; favorite and watchlist on and off; and the list lifecycle. Everything it creates is cleaned up afterwards. Copy `.env.example` to `.env` and fill in an API key plus account credentials. Use a throwaway TMDB account, because the suite really writes to it.

## Attribution

This product uses the TMDB API but is not endorsed or certified by TMDB.

## License

[MIT](LICENSE)

TDQS

B3.4/5.0

Scored across 30 tools

Disambiguation4/5

Most tools have clearly distinct resource+action targets: search vs discover_movies/discover_tv are separated by text-vs-filters, and remove_from_list/clear_list/delete_list are well delineated. The only fuzzy area is the list/account cluster (get_account_lists vs get_list vs get_account_items), where an agent could momentarily misselect, but descriptions resolve it.

Naming Consistency4/5

Predominantly verb_noun / get_noun (get_movie, get_tv_show, create_list, add_to_list, set_watchlist), which is readable and predictable. Minor deviations exist: bare verbs 'search' and 'rate', and the removal verbs alternate between remove_, clear_, and delete_.

Tool Count3/5

30 tools is heavy, though the TMDB surface genuinely spans movies, TV, seasons, episodes, people, account, ratings, and lists, so most tools carry their weight. It still sits well above a comfortable 10-15 range and could be trimmed via append-style consolidation (e.g. the many list operations).

Completeness4/5

Coverage is broad: discovery, text search, external-ID lookup, detail endpoints with append, trending/charts, watch providers, recommendations, ratings, favorites, watchlist, and full custom-list lifecycle. Minor gap: discover filters require company/keyword IDs but search only offers multi/movie/tv/person types, so those IDs are awkward to obtain.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues