Skip to main content
Glama

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.

CI Python 3.12+ FastMCP License: MIT Ruff Latest release

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 webapp

Related MCP server: Plex MCP Server

Documentation map

Read this…

When you care about…

docs/README.md

Hub — every guide in one place

docs/QUICKSTART.md

~60s — MCP only, web UI, RAG pointer

docs/ONBOARDING.md

First run — connect Plex, costs, pitfalls, sanity check

docs/INSTALL.md

Tauri desktop (primary), uv, clone, MCPB, Claude Desktop

docs/TAURI.md

Maintainer: build installer, production pitfalls

docs/DOCUMENTATION_INDEX.md

Full doc map + archival paths

docs/PLEX.md

What Plex is, tokens, remote access (plain language)

docs/ARCHITECTURE.md

How the MCP server, backend, and UI fit together

docs/SELF_HOSTING.md

Home lab: HTTPS, reverse proxy, secrets, hardening

docs/DOCKER.md

Optional Docker Compose example

docs/CONFIGURATION.md

Environment variables, sampling, RAG, *arr

docs/LIBRARY_BUILDING.md

Build a library: folders, naming, agents, ripping legality, rtorrent-mcp handoff

docs/COLLECTORS_TOOLKIT.md

Scene naming, verification, Plex realities, self-audit, lawful links

docs/BITTORRENT_GUIDE.md

Protocol, lawful uses, rtorrent-mcp setup, sourcing-question policy

docs/TOOLS.md

Tool surface (portmanteaus and what they do)

docs/WEBAPP.md

Web app ports, startup, feature pointers

docs/RAG.md

Semantic search and indexing

docs/ENRICHMENT.md

Deep per-item enrichment: Wikipedia + TMDB + JustWatch, LLM dossiers, cross-references

docs/TROUBLESHOOTING.md

Auth, connection, RAG, common errors

docs/DEVELOPMENT.md

Tests, lint, layout for contributors

docs/PRD.md

Product scope and constraints

docs/plans/OPERATIONAL_IMPROVEMENTS.md

Phased doc/DX/ops todo (checklist)

docs/plans/ROADMAP.md

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 tools
agentic_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_stackA
Read-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_mgrA
Destructive

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_helpA
Read-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_libraryA
Destructive

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_enrichmentB
Read-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_playlistA
Destructive

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_qualityA
Destructive

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_reportingA
Read-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_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

    A3.5/5.0

    Scored across 22 tools

    Disambiguation2/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness5/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      A
      maintenance
      A 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.
      54
      506 npm
      57
      JavaScript
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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