PlexMCP
PlexMCP is an MCP server that lets an agent browse, search, curate, stream, and administer a Plex Media Server (plus check the Radarr/Sonarr/Lidarr *arr stack).
Library management (
plex_library): list/get/create/update/delete libraries, scan, refresh, optimize, empty trash, clean bundles, manage paths, and paginate items with sort/type filters.Media discovery (
plex_media,plex_search): browse, keyword and advanced Boolean search (genre, year, actor, director, studio, rating, decade, country), autocomplete suggestions, recent searches, and saved searches.Metadata (
plex_metadata,plex_media,plex_media_enrichment): refresh, fix matches, match/organize items, edit titles/summaries, and pull external context from Wikipedia, TMDB, and TVDB.Collections & playlists (
plex_collections,plex_playlist): full CRUD, add/remove items, and playlist analytics.Playback & streaming (
plex_streaming,plex_audio_mgr): list sessions/clients, play, pause, stop, seek, skip, set quality/volume, switch audio streams, mute, and hand over between clients.RAG semantic search (
plex_rag): natural-language search over metadata and subtitles, plus metadata/subtitle sync and index status.Server & performance (
plex_server,plex_performance,plex_quality): status, health, info, restart/update, maintenance, transcoding and bandwidth stats, quality/transcode profiles, throttling, and rate limits.Organization & maintenance (
plex_organization): reorganize files with dry-run, analyze, clean bundles, and VACUUM/REINDEX database optimization.FFmpeg repair (
plex_ffmpeg_mgr): probe files, sync audio/subtitles, revert backups, extract subtitles/clips/audio, and set aspect ratio.Users (
plex_user): list, create, update, delete users and manage permissions/roles and library restrictions.Reporting (
plex_reporting): library, usage, content, user-activity, and performance reports with JSON/CSV/HTML export.*Integrations & arr stack (
plex_integration,arr_stack): check Radarr/Sonarr/Lidarr health, regional recommendations, European content, anime season info, and configure third-party providers.Agent helpers (
agentic_plex_workflow,plex_natural_assistant,plex_help): multi-step tool-calling workflows, single-turn natural-language Q&A, and self-discovery of tools/examples/API docs.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@PlexMCP search for horror movies in my library"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
PlexMCP
Talk to your library. An open Model Context Protocol server for Plex Media Server — plus an optional glass-style web app for browsing, search, and chat.
Quick start · Install · Web app · All docs · Changelog
Quick Start
Download Plex MCP_*_x64-setup.exe from Releases → double-click → launch Plex MCP. Install guide.
Claude Desktop only (no installer) — latest .mcpb bundle + registration script:
powershell -ExecutionPolicy Bypass -c "irm https://github.com/sandraschi/plexmcp/releases/latest/download/install.ps1 | iex"Developers from source:
git clone https://github.com/sandraschi/plexmcp plex-mcp
cd plex-mcp
just install
just webappRelated MCP server: Plex MCP Server
Documentation map
Read this… | When you care about… |
Hub — every guide in one place | |
~60s — MCP only, web UI, RAG pointer | |
First run — connect Plex, costs, pitfalls, sanity check | |
Tauri desktop (primary), uv, clone, MCPB, Claude Desktop | |
Maintainer: build installer, production pitfalls | |
Full doc map + archival paths | |
What Plex is, tokens, remote access (plain language) | |
How the MCP server, backend, and UI fit together | |
Home lab: HTTPS, reverse proxy, secrets, hardening | |
Optional Docker Compose example | |
Environment variables, sampling, RAG, *arr | |
Build a library: folders, naming, agents, ripping legality, rtorrent-mcp handoff | |
Scene naming, verification, Plex realities, self-audit, lawful links | |
Protocol, lawful uses, rtorrent-mcp setup, sourcing-question policy | |
Tool surface (portmanteaus and what they do) | |
Web app ports, startup, feature pointers | |
Semantic search and indexing | |
Deep per-item enrichment: Wikipedia + TMDB + JustWatch, LLM dossiers, cross-references | |
Auth, connection, RAG, common errors | |
Tests, lint, layout for contributors | |
Product scope and constraints | |
Phased doc/DX/ops todo (checklist) | |
Feature specs and product roadmap |
Stack
MCP server: Python 3.12+ · FastMCP 3.4+ · plexapi · Pydantic 2
Webapp backend: FastAPI · Uvicorn — calls the same Python package as the MCP server in-process, so behavior always matches
Webapp frontend: Next.js 15 · React 18 · TypeScript · Tailwind CSS · lucide-react icons
Search: LanceDB + fastembed for optional semantic/RAG search over your library metadata (see docs/RAG.md for PYTHONPATH notes)
Desktop app: Tauri 2 (Rust) — see docs/TAURI.md
Not currently used: Zustand, Framer Motion (webapp state is local useState/useEffect; no client-side animation library beyond CSS transitions).
License & credits
MIT — LICENSE. Plex, FastMCP, and contributors.
Fleet standards cross-link: mcp-central-docs (e.g. SOTA requirements).
Available Tools
22 toolsagentic_plex_workflowA
Multi-step Plex workflows via FastMCP sampling with tool execution (SEP-1577).
The model chooses plex_* tool calls; the server runs them and feeds results back until the model returns a final text answer or max_iterations is reached.
Return Format
ToolResult with content: {"success": bool, "result": {"final_output": str, "iterations": int, "executed_tools": list}}
Examples
await agentic_plex_workflow(workflow_prompt="Show me my movie libraries", available_tools=["plex_library"])
Inputs: available_tools (required), workflow_prompt (required), max_iterations.
arr_stackARead-only
Query Radarr, Sonarr, and Lidarr HTTP APIs for media stack health.
PORTMANTEAU PATTERN RATIONALE: Consolidates 3 synchronization services into a single tool to match established industry patterns for managing "the stack" as a unified metadata pipeline.
Return Format
{"success": bool, "data": dict, "message": str}
Examples
await arr_stack(operation="status")
Inputs: operation (required).
plex_audio_mgrA
Comprehensive audio management operations for Plex Media Server.
PORTMANTEAU PATTERN RATIONALE: Consolidates 7 audio-focused control operations into a single interface to minimize latency during real-time playback adjustments and stream switching.
Return Format
{"success": bool, "data": dict, "message": str}
Examples
await plex_audio_mgr(operation="list_streams", media_key="12345") await plex_audio_mgr(operation="set_volume", client_id="client-abc", volume=75)
Inputs: operation (required), volume, client_id, media_key, +2 more.
plex_collectionsA
Comprehensive collections management tool for Plex Media Server.
PORTMANTEAU PATTERN RATIONALE: Consolidates 7 collection-related operations into a single tool to facilitate the thematic grouping and organization of cross-library media.
Return Format
{"success": bool, "data": dict, "message": str}
Examples
await plex_collections(operation="list") await plex_collections(operation="create", title="My Collection", library_id="lib1")
Inputs: operation (required), items, title, summary, +2 more.
plex_ffmpeg_mgrADestructive
Industrial-grade FFmpeg management tool for Plex media.
PORTMANTEAU PATTERN RATIONALE: Consolidates low-level media repair and inspection tasks that require system-level FFmpeg binaries. This avoids tool explosion while providing powerful repair capabilities for broken rips or sync-drifted media.
OPERATIONS:
probe: Inspect media file streams and format metadata.
sync_audio: Shift audio track timing by an offset.
sync_subtitles: Shift subtitle track timing by an offset.
revert: Restore the .bak backup of a modified file.
extract_subtitles: Extract a subtitle stream to a sidecar file.
extract_clip: Extract a video segment using FFmpeg with stream copy.
extract_audio: Extract an audio segment as WAV PCM.
set_aspect: Change display aspect ratio (metadata or re-encode).
Return Format
{"success": bool, "data": dict, "message": str}
Examples
await plex_ffmpeg_mgr(operation="probe", media_key="12345") await plex_ffmpeg_mgr(operation="sync_audio", media_key="12345", offset_seconds=-1.5) await plex_ffmpeg_mgr(operation="extract_clip", media_key="12345", start_seconds=30, duration_seconds=10) await plex_ffmpeg_mgr(operation="extract_audio", media_key="12345", start_seconds=60, duration_seconds=15)
Inputs: media_key (required), operation (required), reencode, output_path, +5 more.
plex_helpARead-only
Comprehensive help and discovery tool for PlexMCP.
PORTMANTEAU PATTERN RATIONALE: Consolidates 4 discovery operations into a single tool to facilitate autonomous exploration of available capabilities without requiring external documentation.
OPERATIONS:
help: General ecosystem overview and architectural guidance.
list_tools: Brief enumeration of all available tools and categories.
tool_info: Deep inspection of specific tool syntax and operation modes.
examples: Curated few-shot examples for complex media workflows.
api_docs: Return URLs for Swagger UI, ReDoc, and OpenAPI schema.
Return Format
{"success": bool, "operation": str, "tools": list | None, "help": str | None, "error": str | None}
Examples
await plex_help(operation="help") await plex_help(operation="list_tools") await plex_help(operation="tool_info", tool_name="plex_library") await plex_help(operation="api_docs")
Inputs: operation (required), category, tool_name.
plex_integrationB
Comprehensive third-party integration operations for Plex Media Server.
PORTMANTEAU PATTERN RATIONALE: Consolidates 6 external API integrations into a single tool to provide unified access to regional recommendations and niche metadata providers.
Return Format
{"success": bool, "operation": str, "data": list|dict, "count": int|None, "error": str|None}
Examples
await plex_integration(operation="list_integrations") await plex_integration(operation="vienna_recommendations", content_type="movie", limit=5) await plex_integration(operation="anime_season_info", year=2024, season="spring") await plex_integration(operation="configure", integration_name="vienna", config={"api_key": "..."})
Inputs: operation (required), year, limit, config, +5 more.
plex_libraryADestructive
Comprehensive library management operations for Plex Media Server.
PORTMANTEAU PATTERN RATIONALE: Consolidates 12+ library-related operations into a single tool to prevent tool explosion. Simplifies library lifecycle management (CRUD, scan, optimize) for agents.
OPERATIONS:
list: List all media libraries.
get: Get detailed information about a specific library.
create/update/delete: Manage library existence and settings.
scan/refresh: Update media index and metadata.
optimize/empty_trash/clean_bundles: Maintain library database health.
add_location/remove_location: Manage physical media paths.
list_items: List paginated library contents with sort and type filters.
Return Format
{"success": bool, "data": dict|list, "operation": str, "count": int}
Examples
await plex_library(operation="list") await plex_library(operation="get", library_id="1") await plex_library(operation="scan", library_id="1", force=True) await plex_library(operation="list_items", library_id="1", sort="title", media_type="movie")
Inputs: operation (required), name, path, sort, +10 more.
plex_mediaA
Comprehensive media management operations for Plex Media Server.
PORTMANTEAU PATTERN RATIONALE: Consolidates media browsing, advanced searching, and metadata updates into a single tool. Optimizes for discovery and detail retrieval across all library types.
OPERATIONS:
browse: Browse library contents with optional filtering.
search: Advanced search across libraries with multiple filters.
get_details: Get comprehensive details about a specific media item.
get_recent: Get recently added media items.
update_metadata: Update metadata (title, year, summary) for an item.
Return Format
{"success": bool, "data": dict|list, "operation": str, "count": int}
Examples
await plex_media(operation="browse", library_id="1") await plex_media(operation="search", query="inception") await plex_media(operation="get_details", media_key="12345")
Inputs: operation (required), year, actor, genre, +10 more.
plex_media_enrichmentBRead-only
High-value media enrichment using external sources (Wikipedia, TMDB, TVDB).
This tool adds 'Informed Discovery' capabilities to PlexMCP by fetching contextual metadata that Plex does not natively provide.
PORTMANTEAU PATTERN RATIONALE: Consolidates external metadata discovery into a single enrichment interface.
Return Format
{"success": bool, "data": str, "message": str}
Examples
await plex_media_enrichment(operation="enrich_item", title="Inception", year=2010)
Inputs: title (required), operation (required), year, media_type.
plex_metadataA
Comprehensive metadata management operations for Plex Media Server.
PORTMANTEAU PATTERN RATIONALE: Consolidates 7 metadata lifecycle operations into a single tool to ensure consistent identifier handling and improved discovery of library maintenance tasks.
Return Format
{"success": bool, "operation": str, "data": dict|list, "item_id": str|None, "library_id": str|None}
Examples
await plex_metadata(operation="refresh", library_id="1", force=True) await plex_metadata(operation="refresh_all") await plex_metadata(operation="update", item_id="123", metadata={"title": "New Title"}) await plex_metadata(operation="analyze", library_id="1")
Inputs: operation (required), force, item_id, match_id, +4 more.
plex_natural_assistantA
Single-turn natural-language help about Plex (sampling, no tool execution).
Uses the configured sampling endpoint (Ollama / client). For actions that change server state or need live data, use portmanteau tools or agentic_plex_workflow.
Return Format
ToolResult with content: {"success": bool, "result": {"reply": str, "detail_level": str}}
Examples
await plex_natural_assistant(user_query="What is Plex Transcoding?") await plex_natural_assistant(user_query="How do I optimize my library?", detail_level="detailed")
Inputs: user_query (required), detail_level.
plex_organizationB
Comprehensive library organization and maintenance operations for Plex Media Server.
PORTMANTEAU PATTERN RATIONALE: Consolidates 5 library structural maintenance and database optimization tasks into one tool to streamline the archival and cleanup workflows.
Return Format
{"success": bool, "operation": str, "data": dict|list, "library_id": str|None}
Examples
await plex_organization(operation="organize", library_id="1", dry_run=True) await plex_organization(operation="analyze", library_id="1") await plex_organization(operation="clean_bundles", library_id="1", threshold_days=30) await plex_organization(operation="optimize_database", vacuum=True, reindex=True)
Inputs: operation (required), vacuum, analyze, dry_run, +4 more.
plex_performanceA
Comprehensive performance, quality, and server status operations for Plex Media Server.
PORTMANTEAU PATTERN RATIONALE: Consolidates transcoding settings, bandwidth monitoring, and server health into a single tool.
OPERATIONS:
get_transcode_settings: Get current transcode settings for a quality profile.
update_transcode_settings: Update transcode settings for a quality profile.
get_transcoding_status: Get current transcoding status.
get_bandwidth: Get bandwidth usage statistics.
set_quality: Set streaming quality settings for a profile.
get_throttling: Get current throttling status for a profile.
set_throttling: Enable or disable throttling for a profile.
list_profiles: List all quality profiles.
create_profile: Create a new quality profile.
delete_profile: Delete a quality profile.
get_server_status: Get current server status and health.
get_server_info: Get combined server status and library info.
Return Format
{"success": bool, "operation": str, "data": dict | list, "error": str | None}
Examples
await plex_performance(operation="get_server_status") await plex_performance(operation="set_quality", profile_name="Remote", quality="1080p") await plex_performance(operation="list_profiles")
Inputs: operation (required), bitrate, enabled, quality, +6 more.
plex_playlistADestructive
Comprehensive playlist management operations for Plex Media Server.
PORTMANTEAU PATTERN RATIONALE: Consolidates 8 playlist lifecycle operations into a single tool to provide a unified interface for curation and collaborative list management.
Return Format
{"success": bool, "operation": str, "data": dict|list, "playlist_id": str|None, "count": int|None}
Examples
await plex_playlist(operation="list") await plex_playlist(operation="get", playlist_id="123") await plex_playlist(operation="create", title="My Mix", items=["item1", "item2"]) await plex_playlist(operation="delete", playlist_id="123") await plex_playlist(operation="add_items", playlist_id="123", items=["item3"])
Inputs: operation (required), sort, items, title, +3 more.
plex_qualityADestructive
Comprehensive quality profile management tool for Plex Media Server.
PORTMANTEAU PATTERN RATIONALE: Consolidates 6 quality profile operations into a single tool to standardize transcoding rules and resolution limits across multiple devices.
Return Format
{"success": bool, "operation": str, "profile_name": str|None, "profiles": list|None, "settings": dict|None, "result": dict|None}
Examples
await plex_quality(operation="list_profiles") await plex_quality(operation="get_profile", profile_name="Remote") await plex_quality(operation="create_profile", profile_name="4K Limited", settings={"max_bitrate": 40000}) await plex_quality(operation="delete_profile", profile_name="Old Profile")
Inputs: operation (required), settings, is_default, profile_name.
plex_ragA
RAG integration for Plex Media. Semantic search and metadata enrichment.
PORTMANTEAU PATTERN RATIONALE: Consolidates neural search, metadata vectorization, and external high-value discovery into a single tool to manage the knowledge lifecycle.
OPERATIONS:
semantic_search: Natural language search across indexed Plex metadata (Title, Plot, etc.).
search_subtitles: Semantic search across indexed dialogue/subtitles for deep content discovery.
sync_metadata: Extract and vectorize core metadata into the local store.
sync_subtitles: Download, parse, and index subtitle tracks for semantic dialogue search.
status: Check the health and document counts of RAG indices.
Return Format
{"success": bool, "operation": str, "data": dict | list, "count": int | None, "error": str | None}
Examples
await plex_rag(operation="semantic_search", query="time travel paradox") await plex_rag(operation="sync_metadata", enrich=True) await plex_rag(operation="status")
Inputs: operation (required), limit, query, enrich, +2 more.
plex_reportingARead-only
Comprehensive reporting and analytics tool for Plex Media Server.
PORTMANTEAU PATTERN RATIONALE: Consolidates 6 reporting and server diagnostic operations into a single tool to provide a systematic overview of library growth and server health.
Return Format
ToolResult with content dict: {"success": bool, "operation": str, "stats"/"reports"/"server_status": ...}
Examples
await plex_reporting(operation="library_stats") await plex_reporting(operation="performance_report") await plex_reporting(operation="library_stats", library_id="1")
Inputs: operation (required), format, library_id, time_range, +1 more.
plex_searchA
Comprehensive search management tool for Plex Media Server.
PORTMANTEAU PATTERN RATIONALE: Consolidates 5 search modalities (text, advanced, suggest, history, persistence) into one tool to provide a unified discovery interface for all media types.
OPERATIONS:
search: Keyword-based text search across libraries.
advanced_search: Multi-parameter Boolean filtering (genre, year, actor, etc.).
suggest: Partial query autocomplete and suggestions.
recent_searches: Retrieve recent session search history.
save_search: Persist complex filters for future recall.
Return Format
{"success": bool, "data": dict|list, "operation": str, "count": int}
Examples
await plex_search(operation="search", query="star wars") await plex_search(operation="advanced_search", genre="comedy", year=2020) await plex_search(operation="suggest", query="incept")
Inputs: operation (required), year, actor, genre, +23 more.
plex_serverA
Comprehensive server management operations for Plex Media Server.
PORTMANTEAU PATTERN RATIONALE: Consolidates server lifecycle and maintenance operations into a single tool to prevent tool explosion and improve discoverability of admin-level tasks.
OPERATIONS:
status: Current server availability and basic state.
info: Detailed server identity and library overview.
health: Real-time resource usage and health metrics.
maintenance: Trigger optimization, cleaning, and trash emptying.
restart: Trigger server restart (where supported by OS/wrapper).
update: Check and apply server software updates (where supported).
Return Format
{"success": bool, "data": dict|list, "operation": str}
Examples
await plex_server(operation="status") await plex_server(operation="info") await plex_server(operation="maintenance", maintenance_operation="clean_bundles")
Inputs: operation (required), options, maintenance_operation.
plex_streamingA
Comprehensive playback control and session management operations for Plex Media Server.
PORTMANTEAU PATTERN RATIONALE: Consolidates session monitoring, client discovery, and remote playback control into a single tool.
OPERATIONS:
list_sessions: List all active sessions with client and playback details.
list_clients: List all available Plex clients for remote control.
play: Start media playback on a specific client (auto-selects if omitted).
pause/stop: Control current playback state on a client.
seek: Jump to a specific position (milliseconds) in the media.
skip_next/skip_previous: Navigate through the play queue.
set_volume: Adjust the playback volume (0-100) on a client.
control: Generic playback control for custom actions (e.g., step_forward).
Return Format
{"success": bool, "operation": str, "data": dict, "count": int | None, "error": str | None}
Examples
await plex_streaming(operation="list_sessions") await plex_streaming(operation="play", client_id="abc123", media_key="12345") await plex_streaming(operation="seek", client_id="abc123", seek_to=60000)
Inputs: operation (required), action, offset, volume, +4 more.
plex_userB
Comprehensive user management operations for Plex Media Server.
PORTMANTEAU PATTERN RATIONALE: Consolidates 6 user and access control operations into a single interface to ensure consistent security policy enforcement across shared libraries.
Return Format
ToolResult with content dict: {"success": bool, "operation": str, "data": {...}}
Examples
await plex_user(operation="list") await plex_user(operation="get", user_id="123") await plex_user(operation="create", username="newuser", email="user@example.com", password="secret1234")
Inputs: operation (required), role, email, user_id, +4 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 22 tools
Many tools have overlapping operational boundaries, such as plex_media, plex_metadata, and plex_library all handling metadata updates, plex_search overlapping with plex_media's search functionality, and plex_performance/plex_quality both managing quality profiles. The portmanteau pattern provides some structure but does not fully resolve which tool an agent should select for a given task.
The vast majority of tools follow the plex_<domain> pattern, and even descriptive names like plex_media_enrichment and plex_natural_assistant are readable. However, arr_stack and agentic_plex_workflow break the prefix pattern, and the use of 'mgr' in plex_ffmpeg_mgr and plex_audio_mgr introduces a slight inconsistency. Overall, the naming is predictable and easy to navigate.
22 tools is on the high end of the typical range, but the portmanteau design consolidates dozens of operations into manageable groups. The count feels inflated because many tools cover closely related domains (e.g., four tools touching metadata), but the server's broad scope justifies the number. It is borderline heavy but not excessive.
The server covers an exceptionally broad range of Plex functionality: library CRUD, metadata management, search, playlists, streaming, users, performance, quality, reporting, RAG, integrations, FFmpeg repair, and multi-step workflows. There are no obvious dead ends or missing operations for a Plex-oriented MCP server.
Maintenance
Related MCP Connectors
An MCP server that provides tools to discover and retrieve podcast episodes transcripts.
An MCP server that integrates with Discord to provide AI-powered features.
MCP server for searching Airweave collections with natural language queries.
MCP server for generating rough-draft project plans from natural-language prompts.
Related MCP Servers
- FlicenseAqualityDmaintenanceA Python-based MCP server that integrates with Plex Media Server API to search for movies and manage playlists in your Plex media library.97-
- AlicenseBqualityAmaintenanceA Model Context Protocol server that enables AI assistants to query and manage Plex Media Server content through natural language, providing library access, viewing statistics, and media management capabilities.54506 npm57JavaScriptMIT
- AlicenseNot gradedqualityDmaintenanceEnables users to manage and control their Plex media library through natural language commands in MCP-compatible AI clients. It supports searching content, managing playlists, tracking library statistics, and monitoring live viewing sessions.MIT
- AlicenseAqualityCmaintenanceMCP server for Plex Media Server, focused on media discovery, search, library management, and playback control.25MIT