TV Show Recommender (TMDb) MCP server for AI agents

This MCP server provides TV show recommendations and information by integrating with The Movie Database (TMDb) API. It enables natural language interactions with AI assistants to discover, explore, and get personalized TV show recommendations through the Model Context Protocol.

Installation

Using NPX (Recommended)

The quickest way to run the server without installation:

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

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

Global Installation

# Install globally from NPM
npm install -g tv-recommender-mcp-server

# Set environment variable
export TMDB_API_KEY=your_api_key_here

# Run the server
tv-recommender-mcp-server

Manual Installation

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

# Install dependencies
npm install

# Configure environment variables
# Copy .env-example to .env
# Get an API key from TMDb and add it to the TMDB_API_KEY field

# Build and run
npm run build
npm start

Configuration

Setting Up in Smithery Platform

Visit Smithery platform and log in
Search for "@terryso/tv-recommender-mcp-server" or visit the server page
Click "Install" button
Provide your TMDb API key during configuration
- Get a free API key from TMDb
Once installed, you can use the service in any AI chat that supports Smithery tools

Configuring in Cursor

Create or edit .cursor/mcp.json in your project root
Configure the server (using npx method):

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

Save the file - Cursor will automatically detect and load the MCP server
Use the tool by typing / and selecting TVRecommender

Available Tools

The server provides the following tools:

Show Discovery and Recommendations

get_recommendations_by_genre - Get show recommendations by genre
get_similar_shows - Find shows similar to a specified one
discover_shows - Advanced show discovery with multiple criteria
get_popular_shows - Get currently popular shows
get_trending_shows - Get trending shows (daily or weekly)

Show Information

get_show_details - Get detailed information about a show
get_show_videos - Get trailers and related videos
get_show_reviews - View user reviews for a show
get_watch_providers - Find where to watch a specific show

Actor Information

find_shows_by_actor - Find shows featuring a specific actor
get_recommendations_by_actor - Get recommendations based on an actor
get_actor_details_and_credits - Get actor details and their filmography

Usage Examples

Finding Where to Watch

/TVRecommender get_watch_providers --show_title="Stranger Things" --country_code="US"

Advanced Show Discovery

/TVRecommender discover_shows --with_genres=["Science Fiction", "Thriller"] --vote_average_gte=8.0 --first_air_date_year=2022

Getting Actor Information

/TVRecommender get_actor_details_and_credits --actor_name="Bryan Cranston"

Finding Popular and Trending Shows

/TVRecommender get_popular_shows
/TVRecommender get_trending_shows --time_window="day"

Finding Trailers and Videos

/TVRecommender get_show_videos --show_title="Game of Thrones"

Reading User Reviews

/TVRecommender get_show_reviews --show_title="Breaking Bad" --page=1

Use Cases

Discovering New Shows

Use get_popular_shows or get_trending_shows to find current hot shows
Check details with get_show_details
Watch trailers via get_show_videos
Find where to watch using get_watch_providers

Exploring Shows by Favorite Actor

Look up an actor's works with get_actor_details_and_credits
Get recommendations with get_recommendations_by_actor
Check reviews for interesting shows with get_show_reviews

Precise Show Filtering

Use discover_shows with multiple criteria like genre, year, rating, or keywords to find exactly what you want.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "TVRecommender" '{"command":"env","args":["TMDB_API_KEY=your_api_key_here","npx","tv-recommender-mcp-server"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect

TV Show Recommender (TMDb) MCP server