tv-recommender

This MCP server provides a TMDb-powered set of tools for discovering and exploring American TV series. It exposes a suite of commands such as get_recommendations_by_genre, get_similar_shows, get_show_details, get_watch_providers, discover_shows, and actor-related tools like get_actor_details_and_credits and get_recommendations_by_actor. You interact with the server by sending MCP requests over stdio from an MCP-enabled client. Common workflows include finding popular or trending shows, pulling show details and trailers, and locating where to watch a show in your region. You can also combine tools, for example discovering high-rated sci-fi shows, then drilling into a specific show for details and watch options, or finding other shows by a favorite actor. The server orchestrates calls to the TMDb API and formats responses for the client.

Prerequisites:

• Node.js and npm installed on your machine (Node.js 14+ recommended)
• A TMDb API key (required for TMDb API access)

Option A: Run directly with npx (no local installation)

1. Obtain a TMDb API key from https://www.themoviedb.org/
2. Run the server with npx (the command will fetch the package as needed):

export TMDB_API_KEY=your_api_key_here
npx tv-recommender-mcp-server

Option B: Install globally (install and run locally)

1. Install globally via npm:

npm install -g tv-recommender-mcp-server

2. Set the environment variable and start:

export TMDB_API_KEY=your_api_key_here
tv-recommender-mcp-server

Option C: Clone repository and run locally (recommended for development)

1. Clone the repository:

git clone <repository-url>
cd tv-recommender-mcp-server

2. Install dependencies:

npm install

3. Configure environment:

• Copy .env-example to .env and set TMDB_API_KEY

cp .env-example .env

4. Build and run:

npm run build
npm start

Tips and common issues:

• Ensure TMDB_API_KEY is set in the environment before starting the server; without it the TMDb client will fail to authenticate.
• If you’re using Cursor or Smithery, you can configure mcp.json or environment overrides to supply TMDB_API_KEY per deployment.
• Logs are important for debugging; enable DEBUG=mcp:* to get verbose MCP-level logs in your environment.
• When testing locally, you can use npx tv-recommender-mcp-server or npm run build followed by npm start to run in production-like mode.
• The server is written in TypeScript and uses the MCP SDK; ensure your client supports stdio-based MCP communication.