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.

- 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

# 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): Get from http://www.omdbapi.com/apikey.aspx # - TMDB_API_KEY (required for TV shows): Get from https://www.themoviedb.org/settings/api # - GOOGLE_BOOKS_API_KEY (optional for books): Get from Google Cloud Console # Run migration if you have existing movie data bun run src/migrate-to-media.ts

For use with Claude Desktop or other MCP clients:

# Development (with file watching) bun run dev # Production bun run start

# Set environment variables export API_KEY="your-secure-api-key" export PORT=3000 # optional, defaults to 3000 # Development (with file watching) bun run dev:http # Production bun run start:http

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

- 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

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

- 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

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

- 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

List all media with advanced filtering options.

- 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 a movie to your watchlist (movies you want to watch).

- title(required): Movie title
- year: Release year
- notes: Why you want to watch it
- recommendationContext: Why it was recommended

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

- 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 a movie from your watchlist as watched and rate it.

- id(required): Movie ID
- rating: Your rating (1-10)
- likedAspects: What you liked
- dislikedAspects: What you didn't like
- notes: Your thoughts

Analyze your media preferences to understand your taste.

- 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

Add to your Claude Desktop configuration:

{ "mcpServers": { "mediasage": { "command": "bun", "args": ["run", "/path/to/mediasage/index.ts"] } } }

Endpoint: http://localhost:3000/mcp Method: POST Headers: - Content-Type: text/event-stream - Authorization: Bearer YOUR_API_KEY

- 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 atomdbapi.com)

To enable metadata fetching, get a free API key fromomdbapi.comand set:

export OMDB_API_KEY="your-api-key"

movie-rec-mcp/ ├── index.ts # Main stdio server ├── src/ │ ├── http-server.ts # HTTP/SSE server │ ├── sse-transport.ts # SSE transport implementation │ └── db/ │ ├── index.ts # Database operations │ └── schema.ts # Drizzle schema definitions ├── movies.db # SQLite database (auto-created) └── package.json

Generates dog images with an LGTM (Looks Good To Me) overlay using the Dog CEO API.