Skip to main content
Glama
ericwarthan

Plex-MCP

by ericwarthan
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

Plex MCP Server

A Model Context Protocol server that gives Claude full management access to a Plex Media Server — browsing libraries, fixing metadata, syncing between servers, managing collections, and more.

Works with Claude Desktop (Windows/macOS) and Claude Code via an SSH connection to the Ubuntu host running this server.

Prerequisites

  • Python 3.11+ on the host machine

  • Plex Media Server accessible on your LAN

  • A Plex authentication token (see Finding your token)

  • Claude Desktop or Claude Code

Installation

git clone https://github.com/ericwarthan/Plex-MCP
cd Plex-MCP
python3 -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
pip install -r requirements.txt

Configuration

Copy the example config and fill in your details:

cp config/config.example.json ~/.config/plex-mcp/config.json

Edit ~/.config/plex-mcp/config.json:

{
  "plex_name": "My Plex Server",
  "plex_host": "192.168.1.x",
  "plex_port": 32400,
  "token": "YOUR_PLEX_TOKEN_HERE",
  "plex_url": "http://192.168.1.x:32400"
}

The config file is stored in your home directory (not the repo) so credentials are never accidentally committed.

Connecting to Claude Desktop (Windows)

Claude Desktop connects to the MCP server over SSH. Add this to your %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "plex": {
      "command": "C:\\Program Files\\Git\\usr\\bin\\ssh.exe",
      "args": [
        "username@YOUR_SERVER_IP",
        "cd /home/username/Plex-MCP && source venv/bin/activate && python3 server.py --stdio"
      ]
    }
  }
}

Important — use Git's ssh.exe, not Windows OpenSSH. Claude Desktop launches ssh.exe as a subprocess and reads its stdout as the MCP stream. Windows' built-in OpenSSH (C:\Windows\System32\OpenSSH\ssh.exe) sometimes uses a different key format or agent that fails silently. The SSH binary bundled with Git for Windows (C:\Program Files\Git\usr\bin\ssh.exe) is more reliable for this use case.

Your SSH public key must be in ~/.ssh/authorized_keys on the server host.

Connecting to Claude Code

Claude Code can use the MCP server directly (no SSH wrapper needed if running on the same machine) or via SSH. In your project's .claude/settings.json:

{
  "mcpServers": {
    "plex": {
      "command": "python3",
      "args": ["/home/username/Plex-MCP/server.py", "--stdio"]
    }
  }
}

Or via SSH from a remote machine (same pattern as Claude Desktop above).

Tool Reference

The server exposes 125+ tools across 15 categories. Destructive operations (delete, bulk-mark) require confirmed=true.

Libraries

Tool

Description

library_list

List all libraries with type, item count, and last scan time

library_scan

Trigger a full or partial path scan

library_refresh_metadata

Refresh metadata from agents for all items

library_cancel_scan

Cancel an in-progress scan

library_get_genres

List all genres present in a library

library_get_years

List all release years present

library_get_studios

List all studios present

library_get_directors

List all directors present

library_empty_trash

Permanently remove deleted items from trash

library_create

Create a new library section

library_delete

Permanently delete a library (confirmed=true)

library_update

Rename, change agent/language, or add/remove folder locations

library_settings_get

Read advanced settings (thumbnail gen, intro detection, etc.)

library_settings_set

Update advanced library settings

Movies

Tool

Description

movie_list

List movies with filtering by genre, year, resolution, watched status

movie_recently_added

Movies added most recently

movie_recently_viewed

Recently played movies

movie_on_deck

In-progress / resume-watching movies

movie_get

Full details including cast, GUIDs, media info

movie_search

Search by title

movie_find_candidates

Find correct metadata match candidates

movie_apply_match

Apply a metadata match by GUID

movie_update_metadata

Edit title, sort title, year, summary, studio, rating, etc.

movie_delete

Delete a movie (confirmed=true)

movie_missing_posters

Find all movies without poster artwork

movie_optimize

Queue a pre-transcoded optimized version for a device target

movie_merge

Merge two separate items into one multi-version item

movie_split_media

Split a multi-version item back into separate items

movie_list_merged

List all items with more than one media file attached

movie_list_unmatched

List items with no external metadata agent match

TV Shows

Tool

Description

show_list

List shows with metadata summary

show_get

Full details including season/episode counts, cast

show_seasons

List seasons with episode counts and watch status

show_episodes

List episodes for a season

show_recently_added

Recently added episodes

show_on_deck

Next episodes to watch

show_find_candidates

Find correct metadata match candidates for a show

show_apply_match

Apply a metadata match by GUID

show_update_metadata

Edit metadata on a show, season, or episode

show_delete

Delete a show, season, or episode (confirmed=true)

Artwork

Tool

Description

artwork_get_posters

List all poster options (online + local) with selection state

artwork_get_available

Same as above but also shows provider info for browsing

artwork_set_poster_url

Set poster by downloading from a URL

artwork_set_poster_plex

Select a poster from available options by index

artwork_upload_poster

Upload a poster from a local file path on the server

artwork_lock_poster

Lock poster so metadata refreshes cannot override it

artwork_get_backgrounds

List available background/art images

artwork_set_background_url

Set background art from a URL

artwork_set_background_plex

Select a background by index

artwork_get_banners

List available banner images (TV shows)

artwork_set_banner_url

Set a banner from a URL

artwork_get_themes

List available theme music (TV shows)

Collections

Tool

Description

collection_list

List all collections in a library

collection_get

Get collection details and item list

collection_create

Create a new collection

collection_delete

Delete a collection (confirmed=true)

collection_add_items

Add items to an existing collection (confirmed=true for 10+)

collection_remove_items

Remove items from a collection (confirmed=true for 10+)

collection_set_poster

Set a collection poster from a URL

collection_set_sort_order

Set sort order: release, alpha, or custom

Playlists

Tool

Description

playlist_list

List all playlists

playlist_get

Get playlist details and items

playlist_create

Create a playlist from titles or rating keys

playlist_delete

Delete a playlist (confirmed=true)

playlist_add_items

Add items to a playlist

playlist_remove_items

Remove items from a playlist

Sessions & Playback

Tool

Description

session_list

List active playback sessions

session_transcode_list

List active transcoding sessions

session_terminate

Stop a playback session

session_terminate_transcode

Stop a transcode job

session_history

Recent play history

playback_clients

List available Plex clients

playback_play

Resume playback on a client

playback_pause

Pause playback

playback_stop

Stop playback

playback_seek

Seek to a position

playback_start_media

Start playing a specific item on a client

playback_skip_next

Skip to next item

playback_skip_prev

Skip to previous item

playback_set_volume

Set volume on a client

Watch State

Tool

Description

watch_mark_watched

Mark an item as watched (confirmed=true for 10+ episodes)

watch_mark_unwatched

Mark an item as unwatched (confirmed=true for 10+)

watch_set_rating

Set a star rating (0–10)

watch_get_status

Get watch status, view count, and ratings

watch_bulk_mark_watched

Mark entire library or collection as watched (confirmed=true)

watch_bulk_mark_unwatched

Mark entire library or collection as unwatched (confirmed=true)

Users & Sharing

Tool

Description

user_list

List all managed users and home users

user_get

Get details for a specific user

user_watch_history

Get a user's watch history

user_statistics

Playback statistics for a user

user_share_library

Share a library with a Plex user

user_unshare_library

Remove a user's access to a library

Discovery

Tool

Description

discovery_hubs

Get the home screen hubs (On Deck, Recently Added, etc.)

discovery_on_deck

On Deck items across all libraries

discovery_recently_added

Recently added content across all libraries

discovery_continue_watching

Items with a resume position

discovery_search

Full-text search across all libraries

Music

Tool

Description

music_list_artists

List artists in a music library

music_list_albums

List albums for an artist

music_list_tracks

List tracks for an album

music_get_artist

Full artist details

music_get_album

Full album details including tracks

music_search

Search within a music library

music_update_metadata

Edit artist or album metadata

music_fix_match

Find correct metadata match for an artist or album

music_apply_match

Apply a metadata match by GUID

Server Admin

Tool

Description

server_identity

Server name, version, machine ID

server_capabilities

Feature flags and enabled capabilities

server_preferences

Read all server preferences

server_set_preference

Update a server preference

server_check_updates

Check for available Plex updates

server_apply_update

Apply a pending update

server_activity_log

Recent server activity

server_transient_token

Generate a short-lived access token

server_statistics

Bandwidth and media statistics

Maintenance

Tool

Description

maintenance_empty_all_trash

Empty trash on all libraries (confirmed=true)

maintenance_optimize_database

Run database VACUUM and ANALYZE

maintenance_clean_bundles

Remove orphaned metadata bundle files

maintenance_empty_codecs

Clear the codec cache (confirmed=true)

maintenance_download_logs

Download diagnostics log archive to disk

maintenance_check_orphaned

Find items whose files no longer exist on disk

maintenance_library_info

Storage and metadata statistics for a library

maintenance_server_logs_tail

Recent log lines filtered by level and component

maintenance_library_health

Combined unmatched / merged / orphaned check

Sync

Tool

Description

plex_sync

Copy sort titles, posters, watch state, and collections from a source Plex server to the connected one. Matches items by GUID across both legacy and modern agent formats. Supports dry_run=true to preview changes.

Known Quirks

Git ssh.exe vs Windows OpenSSH Claude Desktop on Windows must use the SSH binary from Git for Windows, not the built-in Windows OpenSSH. Point command to C:\Program Files\Git\usr\bin\ssh.exe. The built-in version at C:\Windows\System32\OpenSSH\ssh.exe often fails silently when Claude Desktop reads the MCP stream from its stdout.

confirmed=true on destructive tools Any tool that deletes items, empties trash, or bulk-modifies many records requires the confirmed parameter set to true. This prevents accidental bulk operations when Claude is exploring or describing what it would do. Always ask Claude to preview first, then confirm.

Poster lock behavior When you upload a custom poster or select a specific one via the artwork tools, the server locks the thumb field so scheduled metadata refreshes cannot overwrite it. To allow Plex to choose the poster again, use movie_update_metadata or the Plex web UI to unlock the field.

plex_sync dry run Always run plex_sync with dry_run=true first. The summary shows every item that would be changed and every GUID that didn't match. Unmatched items usually indicate the source has legacy agent GUIDs that need the mapping table extended — open an issue with the unmatched GUID strings.

License

AGPL-3.0 — free to use and modify, but if you deploy this as a service you must release your modifications under the same license.

This server cannot be installed

F
license - not found
-
quality - not tested
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ericwarthan/Plex-MCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server