TV Recommender

Provides TV show recommendations and details using TMDb data through MCP tools.

typescript

5

GitHub Stars

typescript

Language

4 months ago

First Indexed

3 weeks ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "terryso-tv-recommender-mcp-server": {
      "command": "npx",
      "args": [
        "tv-recommender-mcp-server"
      ],
      "env": {
        "TMDB_API_KEY": "your_api_key_here"
      }
    }
  }
}

You run a Model Context Protocol (MCP) server that provides real-time, personalized TV recommendations and detailed show information by interfacing with the TMDb API. You can query genres, find similar shows, pull show details, and discover content using natural-language style prompts from an MCP-enabled client. This server handles the data retrieval and logic so your chat experience remains seamless and context-aware.

How to use

Interact with an MCP client to discover, compare, and learn about TV shows. You can ask it to recommend by genre, find shows similar to a title, fetch detailed information, or discover content using multi-criteria filters. The server exposes a set of tools that you can invoke from your MCP client to obtain structured results and media links.

Common usage patterns include asking for a genre-based list of shows, requesting similar titles to a known favorite, viewing show details (synopsis, cast, and available trailers), or exploring where to watch a show. The tools are designed to be combined in a natural conversation, so you can refine results by adding constraints like year, rating, or keywords.

How to install

Prerequisites you need on your machine: Node.js and a shell that can run environment-variable exports. You will also need a TMDb API key to fetch data.

# Set your TMDb API key (required)
export TMDB_API_KEY=your_api_key_here

# Run the MCP server via npx
npx tv-recommender-mcp-server

Additional configuration and notes

Environment variables: the MCP server requires a TMDb API key to access data. Set TMDB_API_KEY in your environment before starting the server. If you need to customize other aspects, you can extend your environment with additional variables as needed by your MCP client.

Starting point: the recommended, turnkey way to run is with npx tv-recommender-mcp-server after exporting your TMDB_API_KEY. If you prefer a local installation workflow, you can install globally, or run the project in a local development environment with npm install, build, and start steps as described in the detailed setup options.

Available tools

get_recommendations_by_genre

Fetches show recommendations filtered by one or more genres.

get_similar_shows

Finds shows that are similar to a specified title.

get_show_details

Retrieves detailed information for a specific show, including synopsis, cast, and episodes.

get_watch_providers

Queries where a show can be watched in a given country.

discover_shows

Performs advanced discovery with multiple filters such as genre, rating, year, and keywords.

find_shows_by_actor

Finds TV shows featuring a specified actor.

get_recommendations_by_actor

Provides recommendations based on a particular actor’s filmography and credits.

get_actor_details_and_credits

Fetches actor bios and the list of works they appeared in.

get_popular_shows

Retrieves currently popular shows.

get_trending_shows

Retrieves trending shows within a specified time window.

get_show_videos

Gets trailers and related videos for a show.

get_show_reviews

Fetches user reviews for a show.