Plex MCP Server

Instructions

Implementation Reference

• src/index.ts:1129-1195 (handler)

  The main handler function that implements the get_popular_content tool. It fetches content from all Plex libraries, sorts by viewCount (plays) or lastViewedAt (duration proxy), filters to viewed items only, and returns the top N most popular items.

  private async getPopularContent(timeRange: number, metric: string, mediaType: string, limit: number) {
    try {
      // Get all library content
      const librariesData = await this.makeRequest("/library/sections");
      const libraries = librariesData.MediaContainer?.Directory || [];
      
      let allContent: any[] = [];
      
      for (const library of libraries) {
        try {
          const params: Record<string, any> = {
            "X-Plex-Container-Size": 500,
            sort: metric === "plays" ? "viewCount:desc" : "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 || [];
          allContent.push(...content);
        } catch (error) {
          // Skip libraries that can't be accessed
          continue;
        }
      }
      
      // Filter and sort content
      let filteredContent = allContent.filter((item: any) => 
        item.viewCount && item.viewCount > 0
      );
      
      if (metric === "plays") {
        filteredContent.sort((a: any, b: any) => (b.viewCount || 0) - (a.viewCount || 0));
      } else {
        filteredContent.sort((a: any, b: any) => (b.lastViewedAt || 0) - (a.lastViewedAt || 0));
      }
      
      filteredContent = filteredContent.slice(0, limit);
      
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({
              metric,
              mediaType,
              timeRange: `${timeRange} days`,
              popularContent: filteredContent.map((item: any) => ({
                ratingKey: item.ratingKey,
                title: item.title,
                type: item.type,
                year: item.year,
                viewCount: item.viewCount,
                lastViewedAt: item.lastViewedAt,
                rating: item.rating,
                duration: item.duration,
              })),
            }, null, 2),
          },
        ],
      };
    } catch (error) {
      throw new McpError(ErrorCode.InternalError, `Error getting popular content: ${error}`);
    }
  }

• src/index.ts:202-230 (schema)

  The input schema definition for the get_popular_content tool, defining parameters like timeRange, metric (plays/duration), mediaType, and limit.

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

• src/index.ts:298-304 (registration)

  The switch case in the CallToolRequestSchema handler that routes calls to the getPopularContent method, extracting and defaulting arguments.

  case "get_popular_content":
    return await this.getPopularContent(
      ((args as any)?.timeRange as number) || 30,
      (args as any)?.metric as string || "plays",
      (args as any)?.mediaType as string || "all",
      ((args as any)?.limit as number) || 10
    );

• src/index.ts:201-231 (registration)

  The tool registration in the ListToolsRequestSchema response, including name, description, and input schema.

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