Plex MCP Server

Instructions

Implementation Reference

• src/index.ts:873-928 (handler)

  The core handler function for the 'get_watch_stats' tool. It fetches recent watch history sessions from Plex API, filters by time range, computes statistics based on the specified statType using helper calculate* functions, and returns formatted JSON stats with fallback to basic stats.

  private async getWatchStats(timeRange: number, statType: string) {
    const fromDate = Math.floor((Date.now() - (timeRange * 24 * 60 * 60 * 1000)) / 1000);
    
    try {
      // Get watch history for the time range
      const historyData = await this.makeRequest("/status/sessions/history/all", {
        "X-Plex-Container-Size": 1000,
      });
  
      const sessions = historyData.MediaContainer?.Metadata || [];
      
      // Filter sessions by time range
      const filteredSessions = sessions.filter((session: any) => 
        session.viewedAt && session.viewedAt >= fromDate
      );
  
      let stats: any = {};
  
      switch (statType) {
        case "plays":
          stats = this.calculatePlayStats(filteredSessions);
          break;
        case "duration":
          stats = this.calculateDurationStats(filteredSessions);
          break;
        case "users":
          stats = this.calculateUserStats(filteredSessions);
          break;
        case "libraries":
          stats = this.calculateLibraryStats(filteredSessions);
          break;
        case "platforms":
          stats = this.calculatePlatformStats(filteredSessions);
          break;
        default:
          stats = this.calculatePlayStats(filteredSessions);
      }
  
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({
              timeRange: `${timeRange} days`,
              statType,
              totalSessions: filteredSessions.length,
              stats,
            }, null, 2),
          },
        ],
      };
    } catch (error) {
      // Fallback to basic library stats if detailed history isn't available
      return await this.getBasicStats(timeRange, statType);
    }
  }

• src/index.ts:154-173 (schema)

  Input schema definition for the 'get_watch_stats' tool, specifying parameters timeRange (days, default 30) and statType (enum: plays, duration, users, libraries, platforms, default plays). This is part of the tools list returned by ListToolsRequestHandler.

  {
    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",
        },
      },
    },
  },

• src/index.ts:289-293 (registration)

  Tool dispatch/registration in the CallToolRequestSchema handler switch statement. Routes calls to 'get_watch_stats' to the getWatchStats method with parsed arguments.

  case "get_watch_stats":
    return await this.getWatchStats(
      ((args as any)?.timeRange as number) || 30,
      (args as any)?.statType as string || "plays"
    );

• src/index.ts:930-946 (helper)

  Helper function calculatePlayStats used by getWatchStats for 'plays' statType. Computes daily plays, plays by media type, total plays, and average daily plays from session data.

  private calculatePlayStats(sessions: any[]) {
    const playsByDay: Record<string, number> = {};
    const playsByType: Record<string, number> = {};
    
    sessions.forEach((session: any) => {
      const date = new Date(session.viewedAt * 1000).toISOString().split('T')[0];
      playsByDay[date] = (playsByDay[date] || 0) + 1;
      playsByType[session.type] = (playsByType[session.type] || 0) + 1;
    });
  
    return {
      totalPlays: sessions.length,
      playsByDay,
      playsByType,
      averagePlaysPerDay: sessions.length / Object.keys(playsByDay).length || 0,
    };
  }