MediaSage

A Model Context Protocol (MCP) server that tracks movies, books, and TV shows, providing intelligent recommendations based on your preferences. Built with Bun, SQLite (via Drizzle ORM), and supports both local (stdio) and remote (HTTP/SSE) connections.

Features

• Multi-Media Tracking: Track movies, books, and TV shows with ratings, status, and notes

• Smart Filtering: List media by type, status, rating, genre, and more

• Cross-Media Recommendations: Get suggestions based on your preferences across all media types

• Rich Metadata: Automatic metadata fetching from OMDB (movies), Google Books (books), and TMDB (TV shows)

• Preference Analysis: Understand your favorite genres, creators, and what you typically enjoy

• Persistent Storage: SQLite database with Drizzle ORM and proper relations

• Remote Access: HTTP server with Server-Sent Events (SSE) support

• Secure: API key authentication for remote connections

Installation

Usage

Local Mode (stdio)

For use with Claude Desktop or other MCP clients:

Remote Mode (HTTP/SSE)

For remote access over HTTP:

Available Tools

Movie Tools

search_and_add_movie

Search for a movie and add it with auto-populated metadata from OMDB.

Parameters:

• title (required): Movie title to search for

• year: Release year (helps accuracy)

• watched: Whether you've watched it (default: false)

• rating: Your rating (1-10) if watched

• notes: Personal notes

• likedAspects: What you liked (comma-separated)

• dislikedAspects: What you didn't like

• mood: When/why you watched it

• recommendationContext: How this should influence recommendations

Book Tools

search_and_add_book

Search for a book and add it with auto-populated metadata from Google Books.

Parameters:

• title (required): Book title to search for

• author: Author name (helps accuracy)

• read: Whether you've read it (default: false)

• rating: Your rating (1-10) if read

• notes: Personal notes

• likedAspects: What you liked (comma-separated)

• dislikedAspects: What you didn't like

• mood: When/why you read it

• recommendationContext: How this should influence recommendations

TV Show Tools

search_and_add_tv_show

Search for a TV show and add it with auto-populated metadata from TMDB.

Parameters:

• title (required): TV show title to search for

• year: Year first aired (helps accuracy)

• watched: Whether you've watched it (default: false)

• rating: Your rating (1-10) if watched

• notes: Personal notes

• likedAspects: What you liked (comma-separated)

• dislikedAspects: What you didn't like

• mood: When/why you watched it

• recommendationContext: How this should influence recommendations

General Tools

list_media

List all media with advanced filtering options.

Parameters:

• type: Filter by media type ('movie', 'book', 'tv_show')

• watched_only: Show only watched/read items

• watchlist_only: Show only unwatched/unread items

• min_rating: Minimum rating filter (1-10)

• genre: Filter by genre

• creator: Filter by director/author/creator

• year: Filter by year

add_movie_to_watchlist

Add a movie to your watchlist (movies you want to watch).

Parameters:

• title (required): Movie title

• year: Release year

• notes: Why you want to watch it

• recommendationContext: Why it was recommended

get_smart_recommendations

Get intelligent recommendations based on your preferences across all media types.

Parameters:

• mood: Current mood (e.g., 'action-packed', 'thoughtful')

• genre_preference: Specific genre interest

• length_preference: Preferred length (short/medium/long/any)

• count: Number of recommendations (default: 5)

mark_as_watched

Mark a movie from your watchlist as watched and rate it.

Parameters:

• id (required): Movie ID

• rating: Your rating (1-10)

• likedAspects: What you liked

• dislikedAspects: What you didn't like

• notes: Your thoughts

analyze_preferences

Analyze your media preferences to understand your taste.

update_movie

Update an existing movie entry.

Parameters:

• id (required): Movie ID

• rating: New rating (1-10)

• watched: Update watch status

• notes: Update notes

• likedAspects: Update liked aspects

• dislikedAspects: Update disliked aspects

• mood: Update mood context

Configuration

Claude Desktop

Add to your Claude Desktop configuration:

Remote Client Configuration

Connect to the HTTP endpoint:

Environment Variables

• PORT: HTTP server port (default: 3000)

• API_KEY: Authentication key for remote access (required for HTTP mode)

• OMDB_API_KEY: API key for OMDB movie metadata (get free key at omdbapi.com)

Movie Metadata

The server automatically fetches movie metadata from OMDB API including:

• Directors, cast, genres, plot summaries

• IMDb ratings, Rotten Tomatoes scores

• Release dates, runtime, box office data

• Poster images and more

To enable metadata fetching, get a free API key from omdbapi.com and set:

Workflow

1. Add movies you've watched: Use search_and_add_movie with watched: true and your rating

2. Build your watchlist: Use add_movie_to_watchlist for movies you want to see

3. Rate and analyze: Use mark_as_watched when you watch something from your list

4. Get recommendations: Use get_smart_recommendations for personalized suggestions

5. Understand your taste: Use analyze_preferences to see your movie patterns

Development

The project structure:

Security Notes

• Change the default API key when deploying

• The HTTP server includes CORS headers for development

• Consider using HTTPS in production

• Database file is gitignored for privacy

License

MIT