MediaSage

MediaSage MCP is a multi-media context engine that tracks movies, books, and TV shows, enriching each item with metadata and intelligent recommendations. It supports local usage via a stdio interface for desktop clients and remote access over HTTP with Server-Sent Events, making it easy to build personalized media experiences across devices.

How to use

You interact with MediaSage MCP through a client that talks to either the local stdio server or the remote HTTP server. In local mode, you run commands directly on your machine to add, update, and rate items, build watchlists, and fetch recommendations. In remote mode, you connect to a web endpoint that streams updates and recommendations via Server-Sent Events (SSE) while authenticating with an API key.

Local mode (stdio) lets you develop and test on your computer and then switch to production when you’re ready. Start by launching the dev workflow to watch files and rebuild as you work, or start the production workflow to run a stable server. The primary local commands are:

How to install

Prerequisites: you need Bun installed to run the server, along with a supported shell (bash, zsh, or PowerShell). You will also set API keys for metadata enrichment if you plan to use remote mode.

# Clone the repository
git clone <your-repo-url>
cd mediasage

# Install dependencies
bun install

# Set up API keys (required for metadata enrichment)
cp .env.example .env
# Edit .env and add your API keys:
# - OMDB_API_KEY (required for movies)
# - TMDB_API_KEY (required for TV shows)
# - GOOGLE_BOOKS_API_KEY (optional for books)

# Run migration if you have existing movie data
bun run src/migrate-to-media.ts

Additional setup and configuration

MediaSage MCP supports both local and remote operation. Local mode uses a stdio interface and runs under Bun. Remote mode exposes an HTTP endpoint with SSE support and requires an API key for access.

Environment variables shown in this setup include the HTTP port and the API key. You can customize them when starting the remote server.

Security and maintenance

Change the default API key when deploying to production. The HTTP server includes CORS headers during development, so consider enabling HTTPS for production deployments. The database file is kept private by default.

Usage workflow

Add movies, books, and TV shows with enriched metadata. Build and maintain your watchlists, rate items after you watch or read, and explore personalized recommendations that span all media types. Use preference analysis to understand your tastes and refine your recommendations over time.

Development

Project structure is designed for clear separation between stdio and HTTP servers, plus a local database with ORM integrations. Use the dev workflow to iterate quickly and the start workflow for production readiness.

Notes on metadata

MediaSage fetches movie metadata from OMDB, TV metadata from TMDB, and book metadata from Google Books. To enable this, provide the relevant API keys in your environment. OMDB is required for movies, TMDB for TV shows, and Google Books is optional for books.

Available tools

search_and_add_movie

Search for a movie and add it with auto-populated metadata from OMDB, including parameters for year, watched status, rating, notes, liked/disliked aspects, mood, and a recommendation context.

search_and_add_book

Search for a book and add it with auto-populated metadata from Google Books, including read status, rating, notes, liked/disliked aspects, mood, and a recommendation context.

search_and_add_tv_show

Search for a TV show and add it with auto-populated metadata from TMDB, including year, watched status, rating, notes, liked/disliked aspects, mood, and a recommendation context.

list_media

List all media with advanced filtering options such as type, watched/read status, rating, genre, creator, and year.

add_movie_to_watchlist

Add a movie to your watchlist with title, year, notes, and a recommendation context.

get_smart_recommendations

Get intelligent recommendations across all media types based on mood, genre, length, and count.

mark_as_watched

Mark a media item as watched or read, add a rating, and record liked/disliked aspects and notes.

analyze_preferences

Analyze your media preferences to understand your taste across types.

update_movie

Update an existing movie entry with new rating, status, notes, and mood context.