moviefinder-mcp
An MCP server that wraps The Movie Database (TMDB) API. Built with @modelcontextprotocol/sdk and stdio transport.
Tools
| Tool | Description |
|---|---|
search_movies | Search movies by title, optional year filter. |
search_tv | Search TV shows by title. |
get_movie_details | Full movie details with top cast, directors, and trailer. |
get_recommendations | TMDB recommendations for a movie. |
get_similar | Movies similar to a given movie. |
get_trending | Trending movie / tv / all for day or week. |
where_to_stream | Streaming / rental / purchase providers for a movie (default country US). |
discover_movies | Discover by genre name, min rating, year, and sort order. |
All tools return summarized JSON (id, title, year, overview, rating, poster URL, etc.) — the noisy raw TMDB fields are stripped.
Setup
1. Get a TMDB API token
- Create a free account at https://www.themoviedb.org/.
- Visit https://www.themoviedb.org/settings/api and copy the API Read Access Token (v4). This is a long JWT — it is not the v3 API key.
2. Install and build
npm install
npm run build
3. Configure environment
Copy .env.example to .env and paste your token:
cp .env.example .env
TMDB_API_KEY=eyJhbGciOi...your_v4_read_access_token...
4. Run the server
npm start
The server speaks MCP over stdio and is meant to be launched by an MCP client (such as Claude Desktop), not run interactively.
Register with Claude Desktop
Add an entry to claude_desktop_config.json:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"moviefinder": {
"command": "node",
"args": ["/absolute/path/to/moviefinder-mcp/dist/index.js"],
"env": {
"TMDB_API_KEY": "eyJhbGciOi...your_v4_read_access_token..."
}
}
}
}
Restart Claude Desktop after editing the config. The moviefinder tools will then appear in any conversation.
Scripts
| Script | What it does |
|---|---|
npm run build | Compiles TypeScript to dist/. |
npm start | Runs the compiled server (node dist/index.js). |
npm run dev | TypeScript watch mode. |
Error handling
The server returns helpful messages for common TMDB failures:
- 401 — token missing or wrong key type (must be v4 read access token).
- 404 — the requested movie / resource does not exist.
- 429 — rate limited; the
Retry-Aftervalue is included when present.
Notes
- Genre list is fetched once from
/genre/movie/listand cached in memory. - Poster URLs use
https://image.tmdb.org/t/p/w500. - No database, no logging framework — by design.