# Plex MCP > Plex connects your AI agent directly to your private media library. Search, manage, and track everything from movies and TV shows to photos and music without opening a single app. Check who's watching what right now, find detailed cast information for any title, or even mark items as watched using only natural conversation. ## Overview - **Category:** content-management - **Price:** Free - **Tags:** media-server, streaming, library-management, playback-control, media-metadata, self-hosted ## Description Tired of juggling multiple apps just to check your home media? This MCP connects your AI agent straight into your Plex Media Server, letting you manage your entire library through simple talk. You can ask it things like, 'Who's watching that detective show right now?' or 'What are the best-reviewed sci-fi movies I haven't seen?' It pulls all that data together instantly. Because Vinkius hosts this connector, you connect once from any compatible AI client and get immediate access to your entire media collection management system. You can ask it for detailed information on an actor's filmography or list every playlist you've ever made. This isn't just a search tool; it lets you monitor active streaming sessions and even tell the server, 'Mark this movie as watched.' It makes managing thousands of files feel like chatting with a smart librarian. ## Tools ### get_all_episodes Retrieves a complete list of episodes for any given television series. ### get_children Finds related content, such as getting all seasons from a show or all albums from an artist. ### get_libraries Lists every major section on your server, detailing what type of media it holds (movies, photos, etc.). ### get_library_content Filters and retrieves all content from a specific library you designate. ### get_metadata Gathers deep details on any item, including the director, cast list, summary, and original file path. ### get_on_deck Identifies the next unwatched episode or album you should watch to continue a series. ### get_playlist_items Pulls all the specific items, titles, and types contained within a playlist. ### get_playlists Lists every single playlist you have created on the server, along with their content count and type. ### get_recently_added Shows a list of all movies, albums, or episodes that were recently added to your media library. ### get_server_info Provides basic information and status checks for the entire Plex Media Server instance. ### get_sessions Lists all currently active viewing sessions, including who is watching what and their playback progress. ### mark_unwatched Resets the watch status of a media item so it will appear as unwatched again. ### mark_watched Updates an item's record to show that you have finished watching it, removing it from 'On Deck'. ### refresh_library Forces the server to re-scan a designated library after you've manually added or changed media files. ### search_library Searches across all your libraries for specific titles, episodes, or artists by name. ## Prompt Examples **Prompt:** ``` Show me what's currently playing on my Plex server. ``` **Response:** ``` Active sessions: 1. User 'John' watching 'The Last of Us S01E03' at 34:15/58:22 (Roku, Direct Play). 2. User 'Sarah' watching 'Oppenheimer' at 1:45:30/3:00:15 (iPhone, Transcoding 1080p). ``` **Prompt:** ``` Show me my movie libraries. ``` **Response:** ``` Found 3 libraries: 1. 'Movies' (key: 1, type: movie, 1,245 items) — 2. '4K Movies' (key: 5, type: movie, 342 items) — 3. 'Kids Movies' (key: 8, type: movie, 189 items). ``` **Prompt:** ``` What's on deck for me to watch? ``` **Response:** ``` On Deck: 1. 'The Mandalorian S03E05' — 2. 'Stranger Things S04E07' — 3. 'Ted Lasso S02E03' — 4. 'The Office S07E19' — 5. 'Severance S01E04'. All are next unwatched episodes of shows you're currently watching. ``` ## Capabilities ### View Server Health Status Check if the Plex Media Server is running correctly and get its current version information. ### Monitor Active Streams See a real-time list of every user who is currently watching media, including their progress and device type. ### Browse Media Collections List all major sections on your server, such as 'Movies,' 'TV Shows,' or 'Music' libraries. ### Find Specific Content Details Pull comprehensive details about any item, including its cast, genre, runtime, and file path. ### Manage Viewing Progress Update an item's status by marking it as watched or unwatched directly through conversation. ## Use Cases ### Tracking a Mystery Viewing Session A family member asks their agent, 'What is currently playing in the living room?' The agent uses `get_sessions` to reply with real-time details, including the user's name and exact playback progress. No guesswork necessary. ### Building a Watchlist of New Content A user asks for all new sci-fi additions since last week. The agent uses `get_recently_added` combined with `search_library`, pulling titles and metadata instantly, saving hours of manual browsing. ### Debugging Library Issues The server admin runs into a new folder that isn't showing up. They use the agent to execute `refresh_library` on that specific section, fixing the indexing problem immediately. ### Curating a Themed Playlist Instead of manually finding and adding items, the user asks the agent to list all music from a certain era. The agent uses `get_playlists` followed by `get_library_content` to build a perfect playlist structure. ## Benefits - Stop guessing what to watch. Use the `get_on_deck` tool to instantly see the next unwatched episode for any series you follow. - Keep track of every viewing habit with `get_sessions`. You immediately know who's watching and where they left off, which is great for family coordination. - Need proof that your server is working? Running `get_server_info` verifies connectivity and checks the overall health status in seconds. - Organize content by pulling specific item lists using `get_library_content`. You can filter results to only see movies or photos from a particular collection. - Manage history effortlessly. Use `mark_watched` when you finish an episode, keeping your 'On Deck' list accurate and reducing manual clicks. - Quickly find that obscure movie detail using `get_metadata`, getting the director, full cast, and summary without navigating deep menus. ## How It Works The bottom line is you talk to your AI agent, which talks to Plex, and you get an answer without ever opening the Plex app. 1. Subscribe to the Plex MCP and provide your specific Plex Token and Server URL. 2. Connect this MCP to your preferred agent via Vinkius, granting it access permissions for reading media data. 3. Ask your AI client a question like, 'Show me what's next in my watchlist,' and the tool returns the required content. ## Frequently Asked Questions **How does the Plex MCP know what content I own?** The MCP connects directly to your private Plex Media Server via a secure token. It can only access data that resides on your server, so it's always using your local library information. **Can the Plex MCP help me find my favorite movie details?** Yes. Using `get_metadata`, you can get comprehensive reports on any item, including its cast list, genre, and runtime, all through natural conversation. **Does the Plex MCP track who is watching what?** Absolutely. The `get_sessions` tool provides a real-time dashboard showing every user currently streaming media, along with their progress and device type. **How do I update my watch history using the Plex MCP?** You use the dedicated status tools. Simply asking the agent to `mark_watched` or `mark_unwatched` handles the necessary database updates for you. **Can the Plex MCP refresh my library if I add new files?** Yes, after manually adding media, you can use the `refresh_library` tool. This forces a scan of that specific section so your AI agent sees the new content immediately.