Plex MCP Server

Instructions

Implementation Reference

• src/index.ts:594-629 (handler)

  The handler function that implements the core logic for the get_media_details tool. It makes an API request to retrieve metadata for the specified ratingKey and returns a formatted JSON response with details like title, type, summary, genres, actors, directors, and viewing stats.

  private async getMediaDetails(ratingKey: string) {
    const data = await this.makeRequest(`/library/metadata/${ratingKey}`);
    const item = data.MediaContainer?.Metadata?.[0];
  
    if (!item) {
      throw new McpError(ErrorCode.InvalidRequest, `Media item not found: ${ratingKey}`);
    }
  
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({
            details: {
              ratingKey: item.ratingKey,
              title: item.title,
              type: item.type,
              year: item.year,
              summary: item.summary,
              rating: item.rating,
              duration: item.duration,
              genres: item.Genre?.map((g: any) => g.tag) || [],
              actors: item.Role?.map((r: any) => r.tag) || [],
              directors: item.Director?.map((d: any) => d.tag) || [],
              writers: item.Writer?.map((w: any) => w.tag) || [],
              studios: item.Studio?.map((s: any) => s.tag) || [],
              addedAt: item.addedAt,
              updatedAt: item.updatedAt,
              viewCount: item.viewCount,
              lastViewedAt: item.lastViewedAt,
            },
          }, null, 2),
        },
      ],
    };
  }

• src/index.ts:99-108 (schema)

  Input schema definition for the tool, specifying that a 'ratingKey' string parameter is required.

  inputSchema: {
    type: "object",
    properties: {
      ratingKey: {
        type: "string",
        description: "The rating key of the media item",
      },
    },
    required: ["ratingKey"],
  },

• src/index.ts:96-109 (registration)

  Tool registration in the ListToolsRequestSchema handler, including name, description, and input schema.

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

• src/index.ts:276-277 (registration)

  Dispatch/registration in the CallToolRequestSchema switch statement that routes calls to the handler.

  case "get_media_details":
    return await this.getMediaDetails((args as any)?.ratingKey as string);