Plex MCP Server

Instructions

Implementation Reference

• src/index.ts:1197-1341 (handler)

  The primary handler function implementing the get_watch_history tool logic. Fetches session history from Plex API (/status/sessions/history/all), applies filters for user/mediaType, computes progress/completion, returns formatted JSON response. Includes fallback using library metadata if direct history unavailable.
  private async getWatchHistory(limit: number, userId?: string, mediaType: string = "all") { try { // Try primary watch history endpoint const params: Record<string, any> = { "X-Plex-Container-Size": limit, sort: "date:desc", }; if (userId) { params.accountID = userId; } const data = await this.makeRequest("/status/sessions/history/all", params); let sessions = data.MediaContainer?.Metadata || []; // Filter by media type if specified if (mediaType !== "all") { const typeMap: Record<string, string> = { movie: "movie", show: "show", episode: "episode" }; sessions = sessions.filter((session: any) => session.type === typeMap[mediaType]); } return { content: [ { type: "text", text: JSON.stringify({ watchHistory: sessions.map((session: any) => ({ sessionKey: session.sessionKey, ratingKey: session.ratingKey, title: session.title, type: session.type, year: session.year, viewedAt: session.viewedAt, duration: session.duration, viewOffset: session.viewOffset, user: session.User?.title, player: session.Player?.title, platform: session.Player?.platform, progress: session.viewOffset && session.duration ? Math.round((session.viewOffset / session.duration) * 100) : 0, completed: session.viewOffset && session.duration ? session.viewOffset >= (session.duration * 0.9) : false, })), totalSessions: sessions.length, }, null, 2), }, ], }; } catch (error) { // Fallback: Create pseudo-history from library metadata try { const librariesData = await this.makeRequest("/library/sections"); const libraries = librariesData.MediaContainer?.Directory || []; let allViewedItems: any[] = []; for (const library of libraries) { try { const params: Record<string, any> = { "X-Plex-Container-Size": Math.ceil(limit / libraries.length) + 5, sort: "lastViewedAt:desc", }; if (mediaType !== "all") { params.type = this.getPlexTypeId(mediaType); } const contentData = await this.makeRequest(`/library/sections/${library.key}/all`, params); const content = contentData.MediaContainer?.Metadata || []; // Filter for items that have been viewed const viewedContent = content.filter((item: any) => item.lastViewedAt && item.viewCount > 0 ); // Convert to history-like format const historyItems = viewedContent.map((item: any) => ({ ratingKey: item.ratingKey, title: item.title, type: item.type, year: item.year, lastViewedAt: item.lastViewedAt, viewCount: item.viewCount, duration: item.duration, viewOffset: item.viewOffset || 0, library: library.title, })); allViewedItems.push(...historyItems); } catch (libError) { continue; } } // Sort by last viewed date and take requested number allViewedItems.sort((a: any, b: any) => (b.lastViewedAt || 0) - (a.lastViewedAt || 0)); allViewedItems = allViewedItems.slice(0, limit); return { content: [ { type: "text", text: JSON.stringify({ watchHistory: allViewedItems.map((item: any) => ({ ratingKey: item.ratingKey, title: item.title, type: item.type, year: item.year, lastViewedAt: item.lastViewedAt, viewCount: item.viewCount, duration: item.duration, viewOffset: item.viewOffset, library: item.library, progress: item.viewOffset && item.duration ? Math.round((item.viewOffset / item.duration) * 100) : 0, completed: item.viewOffset && item.duration ? item.viewOffset >= (item.duration * 0.85) : item.viewCount > 0, })), totalSessions: allViewedItems.length, note: "Generated from library metadata (fallback method)", }, null, 2), }, ], }; } catch (fallbackError) { return { content: [ { type: "text", text: JSON.stringify({ error: "Watch history not available", message: "Unable to retrieve watch history from this Plex server", suggestion: "This feature may require Plex Pass or detailed logging to be enabled", watchHistory: [], }, null, 2), }, ], }; } } }
• src/index.ts:232-255 (schema)

  Input schema definition for the get_watch_history tool, specifying parameters: limit (number, default 50), userId (optional string), mediaType (enum: movie/show/episode/all, default 'all').
  { name: "get_watch_history", description: "Get detailed watch history with session information", inputSchema: { type: "object", properties: { limit: { type: "number", description: "Number of sessions to return (default: 50)", default: 50, }, userId: { type: "string", description: "Filter by specific user ID (optional)", }, mediaType: { type: "string", description: "Filter by media type", enum: ["movie", "show", "episode", "all"], default: "all", }, }, }, },
• src/index.ts:305-310 (registration)

  Tool registration in the central CallToolRequestSchema switch dispatcher: maps 'get_watch_history' calls to the getWatchHistory handler with parsed arguments.
  case "get_watch_history": return await this.getWatchHistory( ((args as any)?.limit as number) || 50, (args as any)?.userId as string, (args as any)?.mediaType as string || "all" );
• src/index.ts:44-257 (registration)

  Tool registration in ListToolsRequestSchema handler: includes get_watch_history in the advertised tools list with name, description, and inputSchema.
  this.server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ { name: "get_libraries", description: "Get all Plex libraries", inputSchema: { type: "object", properties: {}, }, }, { name: "search_media", description: "Search for media in Plex libraries", inputSchema: { type: "object", properties: { query: { type: "string", description: "Search query", }, type: { type: "string", description: "Media type (movie, show, episode, artist, album, track)", enum: ["movie", "show", "episode", "artist", "album", "track"], }, }, required: ["query"], }, }, { name: "get_recently_added", description: "Get recently added media", inputSchema: { type: "object", properties: { limit: { type: "number", description: "Number of items to return (default: 10)", default: 10, }, }, }, }, { name: "get_on_deck", description: "Get on deck (continue watching) items", inputSchema: { type: "object", properties: {}, }, }, { name: "get_media_details", description: "Get detailed information about a specific media item", inputSchema: { type: "object", properties: { ratingKey: { type: "string", description: "The rating key of the media item", }, }, required: ["ratingKey"], }, }, { name: "get_recently_watched", description: "Get recently watched movies and shows", inputSchema: { type: "object", properties: { limit: { type: "number", description: "Number of items to return (default: 25)", default: 25, }, mediaType: { type: "string", description: "Filter by media type (movie, show, episode, all)", enum: ["movie", "show", "episode", "all"], default: "all", }, }, }, }, { name: "get_fully_watched", description: "Get all fully watched movies and shows from a library", inputSchema: { type: "object", properties: { libraryKey: { type: "string", description: "Library section key (optional, searches all if not provided)", }, mediaType: { type: "string", description: "Filter by media type (movie, show, all)", enum: ["movie", "show", "all"], default: "all", }, limit: { type: "number", description: "Number of items to return (default: 100)", default: 100, }, }, }, }, { name: "get_watch_stats", description: "Get comprehensive watch statistics (Tautulli-style analytics)", inputSchema: { type: "object", properties: { timeRange: { type: "number", description: "Time range in days (default: 30)", default: 30, }, statType: { type: "string", description: "Type of statistics to retrieve", enum: ["plays", "duration", "users", "libraries", "platforms"], default: "plays", }, }, }, }, { name: "get_user_stats", description: "Get user-specific watch statistics", inputSchema: { type: "object", properties: { timeRange: { type: "number", description: "Time range in days (default: 30)", default: 30, }, }, }, }, { name: "get_library_stats", description: "Get library-specific statistics", inputSchema: { type: "object", properties: { libraryKey: { type: "string", description: "Library section key (optional)", }, }, }, }, { name: "get_popular_content", description: "Get most popular content by plays or duration", inputSchema: { type: "object", properties: { timeRange: { type: "number", description: "Time range in days (default: 30)", default: 30, }, metric: { type: "string", description: "Sort by plays or total duration", enum: ["plays", "duration"], default: "plays", }, mediaType: { type: "string", description: "Filter by media type", enum: ["movie", "show", "episode", "all"], default: "all", }, limit: { type: "number", description: "Number of items to return (default: 10)", default: 10, }, }, }, }, { name: "get_watch_history", description: "Get detailed watch history with session information", inputSchema: { type: "object", properties: { limit: { type: "number", description: "Number of sessions to return (default: 50)", default: 50, }, userId: { type: "string", description: "Filter by specific user ID (optional)", }, mediaType: { type: "string", description: "Filter by media type", enum: ["movie", "show", "episode", "all"], default: "all", }, }, }, }, ], };