Plex MCP Server

A powerful Model-Context-Protocol (MCP) server for interacting with Plex Media Server. It provides a standardized JSON-based interface for automation, AI agents (like Claude), and custom integrations.

Features

• Standardized API: Unified JSON responses for all Plex operations.
• Multiple Transports: Supports both stdio and SSE (Server-Sent Events).
• Comprehensive Control: Manage libraries, media, collections, playlists, clients, and users.
• Remote Ready: Built-in OAuth 2.1 support for integration with remote AI platforms like Claude.ai.
• Admin Tools: Access logs, monitor bandwidth, and run Butler tasks.

Installation

Option 1: Using uv (Recommended)

Run directly without installation:

uvx plex-mcp-server --transport stdio --plex-url http://your-server:32400 --plex-token your-token

Option 2: Install via pip

pip install plex-mcp-server

Option 3: Development / Source

git clone https://github.com/vladimir-tutin/plex-mcp-server.git
cd plex-mcp-server
pip install -e .

Configuration

Set your Plex server URL and Token using one of these methods:

1. Command Line Arguments

plex-mcp-server --plex-url "http://192.168.1.10:32400" --plex-token "ABC123XYZ"

2. Environment Variables (.env)

Create a .env file in the current directory or ~/.config/plex-mcp-server/.env:

PLEX_URL=http://localhost:32400
PLEX_TOKEN=your-authentication-token
MCP_OAUTH_ENABLED=false

or with OAuth Enabled

PLEX_URL=http://localhost:32400
PLEX_TOKEN=your-authentication-token
MCP_OAUTH_ENABLED=true
MCP_OAUTH_ISSUER=https://auth.example.com/application/o/plexmcp-oauth/
MCP_SERVER_URL=https://plexmcp.example.com

3. MCP Client Config

Example for Claude Desktop (%APPDATA%/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "plex": {
      "command": "uvx",
      "args": [
        "plex-mcp-server",
        "--transport",
        "stdio",
        "--plex-url",
        "http://your-server:32400",
        "--plex-token",
        "your-token"
      ]
    }
  }
}

4. Claude Connector Installation

Go to https://claude.ai/settings/connectors and add a new connector with the following settings:

• Name: Plex MCP
• URL: https://plexmcp.example.com/sse
• Add OAuth Client ID and Client Secret if OAuth is enabled

Command Reference

Library Module

Tools for exploring and managing your Plex libraries.

Command	Description	Parameters
library_list	Lists all available libraries.	None
library_get_stats	Gets statistics (count, size, types) for a library.	library_name
library_refresh	Triggers a metadata refresh for a library.	library_name
library_scan	Scans a library for new files.	library_name
library_get_details	Gets detailed information about a library.	library_name
library_get_recently_added	Lists recently added items in a library.	library_name, limit: int
library_get_contents	Lists all items in a library.	library_name, limit: int

Media Module

Tools for searching, inspecting, and editing specific media items.

Command	Description	Parameters
media_search	Search for media across all libraries.	query, library_name, content_type
media_get_details	Get comprehensive details for an item.	media_title, library_name, media_id
media_edit_metadata	Update tags, genres, summary, or title.	media_title, library_name, new_title, new_summary, new_rating, new_release_date, new_genre, remove_genre, new_director, new_studio, new_tags
media_delete	Remove an item from Plex.	media_title, library_name, media_id
media_get_artwork	Retrieve posters or background artwork.	media_title, library_name, art_type: str
media_set_artwork	Set artwork from a local path or URL.	media_title, library_name, poster_path, poster_url, background_path, background_url
media_list_available_artwork	List alternative artwork available for selection.	media_title, library_name, art_type

Playlist Module

Manage your personal and shared playlists.

Command	Description	Parameters
playlist_list	List all available playlists.	None
playlist_get_contents	List items contained in a playlist.	playlist_title, playlist_id
playlist_create	Create a new playlist from items.	title, items: List[str]
playlist_delete	Delete a playlist.	playlist_title, playlist_id
playlist_add_to	Add media items to a playlist.	playlist_title, items: List[str], playlist_id
playlist_remove_from	Remove specific items from a playlist.	playlist_title, items: List[str], playlist_id
playlist_edit	Change playlist title or summary.	playlist_title, new_title, new_summary, playlist_id
playlist_upload_poster	Upload a custom poster image.	playlist_title, image_path, playlist_id
playlist_copy_to_user	Share/Copy a playlist to another user.	playlist_title, username, playlist_id

Collection Module

Organize movies and shows into collections.

Command	Description	Parameters
collection_list	List collections in a specific library.	library_name
collection_create	Create a new collection.	library_name, title, items: List[str]
collection_add_to	Add items to an existing collection.	library_name, collection_title, items: List[str], collection_id
collection_remove_from	Remove items from a collection.	library_name, collection_title, items: List[str], collection_id
collection_edit	Edit collection metadata and settings.	collection_title, collection_id, library_name, new_title, new_sort_title, new_summary, new_content_rating, new_labels, add_labels, remove_labels, poster_path, poster_url, background_path, background_url, new_advanced_settings
collection_delete	Delete a collection.	collection_title, collection_id, library_name

User Module

Information about the server owner and shared users.

Command	Description	Parameters
user_search_users	Search for shared users.	search_term
user_list_all_users	List all users with types and IDs.	None
user_get_info	Detailed info for a specific user.	username
user_get_on_deck	Get "On Deck" items for a user.	username
user_get_continue_watching	Get partially watched items to resume.	limit: int
user_get_watch_history	Retrieve personal watch history.	username, limit, content_type, user_id
user_get_statistics	Watch progress and usage statistics.	time_period, username

Sessions Module

Monitor real-time server activity.

Command	Description	Parameters
sessions_get_active	Get currently playing items and clients.	None
sessions_get_media_playback_history	History for a specific media item.	media_title, library_name, media_id

Server Module

Maintenance and administrative tools.

Command	Description	Parameters
server_get_plex_logs	Retrieve lines from Plex logs.	num_lines, log_type, start_line, list_files, search_term
server_get_info	Basic server health and version info.	None
server_get_bandwidth	Bandwidth usage statistics.	timespan, lan
server_get_current_resources	CPU/Memory usage of the host/process.	None
server_get_butler_tasks	List scheduled maintenance tasks.	None
server_get_alerts	Listen for server notifications/alerts.	timeout
server_run_butler_task	Manually trigger a Butler task.	task_name
server_empty_trash	Empty trash for libraries.	library_name
server_optimize_database	Run database optimization.	None
server_clean_bundles	Clean up unused media bundles.	None

Client Module

Control playback and navigation on Plex clients.

Command	Description	Parameters
client_list	List all available playback clients.	include_details: bool, active_only: bool
client_get_details	Detailed info for a client.	client_name, client_id
client_get_timelines	Current playback state/trackers.	client_name, client_id
client_start_playback	Start playing a media item on a client.	media_title, client_name, rating_key, offset, library_name, use_external_player
client_control_playback	Play, Pause, Stop, Seek, Skip.	client_name, action, offset, client_id
client_navigate	Send remote control navigation commands.	client_name, command, client_id
client_set_streams	Changes audio or subtitle tracks.	client_name, audio_stream_id, subtitle_stream_id, client_id

Remote Access & OAuth

The Plex MCP Server can be integrated with remote platforms like Claude.ai via SSE and optional OAuth 2.1. This allows you to talk to your MCP server directly from the Claude interface from anywhere.

Enabling OAuth

1. Set MCP_OAUTH_ENABLED=true in your environment.
2. Configure MCP_OAUTH_ISSUER (e.g., your OAuth provider URL).
3. Set MCP_SERVER_URL to your public-facing URL.
4. Configure your client to use your OAuth provider Client ID and Secret

Discovery Endpoints

When OAuth is active, the following standard endpoints are exposed:

• /.well-known/oauth-protected-resource
• /.well-known/oauth-authorization-server

Response Formats

All tools return information in JSON format for consistent parsing.

Success Example

{
  "status": "success",
  "data": {
    "title": "Inception",
    "year": 2010,
    "rating": 8.8
  }
}

Error Example

{
  "status": "error",
  "message": "Library 'Missing' not found."
}

Multiple Matches

If an operation finds multiple items with the same name, it returns a list of specific identifiers:

[
  {
    "title": "The Office",
    "id": 123,
    "type": "show",
    "year": 2005
  },
  {
    "title": "The Office",
    "id": 456,
    "type": "show",
    "year": 1995
  }
]

Troubleshooting OAuth

• 401 Unauthorized: Ensure your MCP_OAUTH_ISSUER exactly matches the issuer URL in your identity provider (including trailing slashes).
• Public URL: MCP_SERVER_URL must be reachable by the client (e.g., plexmcp.example.com) and should use HTTPS.
• Redirect URIs: For Claude.ai, the redirect URI in your provider must be https://claude.ai/api/mcp/auth_callback.