tmdb-mcp
# tmdb-mcp
[](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
Scored across 30 tools
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.
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_.
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).
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.