Plex Claude Plugin

A Claude MCP plugin for Plex Media Server administration. Provides automated library updates, intelligent media file naming, and automatic ingestion with folder watching.

Features

• Library Management: List, search, and trigger scans on Plex libraries

• Media Identification: Parse filenames with guessit, verify against TMDb, construct Plex-compliant names

• Batch Processing: Identify and rename entire directories of media files in one operation

• Auto-Ingestion: Watch a folder for new media files, automatically identify, rename, copy to libraries, and trigger scans

• Safety Model: Three-tier tool classification (read/write/blocked) prevents accidental damage

Related MCP server: Plex Assistant MCP

Architecture

Built as a Python MCP server using FastMCP, following the same patterns as the TrueNAS Claude Plugin.

Claude Desktop / Claude Code
  |  stdio (MCP)
  v
MCP Server (FastMCP)
  +-- PlexClient (python-plexapi)
  +-- MediaMatcher (guessit + TMDb)
  +-- FileManager (copy/rename/move)
  +-- IngestWatcher (watchdog)
  +-- IngestHistory (SQLite audit log)

Requirements

• Python 3.11+

• Plex Media Server with API access

• TMDb API key (free at https://www.themoviedb.org/settings/api)

• uv package manager

Quick Start

📖 See QUICKSTART.md for detailed setup instructions!

1. Interactive Configuration (Recommended)

cd videodrome-plugin/montreal-v1
./setup-config.sh

This wizard will:

• ✓ Guide you through all settings

• ✓ Test Plex and TMDb connections

• ✓ Save configuration to .env file

2. Test the Server

uv run --env-file .env videodrome

You should see: Plex MCP Server started successfully!

3. Connect to Claude

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "plex": {
      "command": "uv",
      "args": [
        "--directory", "/FULL/PATH/TO/videodrome-plugin/montreal-v1",
        "run", "--env-file", ".env", "videodrome"
      ]
    }
  }
}

Important: Use absolute path and restart Claude Desktop!

Installation

Claude Desktop (.mcpb)

Download the latest .mcpb file from Releases and open it with Claude Desktop.

Claude Code (Plugin)

claude plugin install /path/to/videodrome-plugin

Manual Configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "plex": {
      "command": "uv",
      "args": ["--directory", "/path/to/videodrome-plugin", "run", "videodrome"],
      "env": {
        "PLEX_URL": "http://192.168.1.100:32400",
        "PLEX_TOKEN": "your-plex-token",
        "TMDB_API_KEY": "your-tmdb-api-key",
        "PLEX_MEDIA_ROOT": "/data/media",
        "PLEX_INGEST_DIR": "/data/ingest"
      }
    }
  }
}

Configuration

MCP Tools

Read-only (auto-approved)

• list_libraries - List Plex library sections

• list_recent - Recently added items

• search_library - Search by title

• get_server_info - Server status

• list_directory - List local files

• parse_filename - Parse with guessit

• search_tmdb - Search TMDb

• get_tmdb_details / get_tmdb_episode - TMDb metadata

• preview_rename - Preview Plex-compliant name

• batch_identify - Identify all files in a directory

• get_watcher_status - Watcher state

• get_ingest_queue - Pending review items

• get_ingest_history - Past operations

Write (require confirmation)

• scan_library - Trigger library scan

• rename_file / copy_file / move_file - File operations

• create_directory - Create folder structure

• execute_naming_plan - Batch rename/copy

• execute_ingest - Full ingest pipeline

• start_watcher / stop_watcher - Control watcher

• approve_ingest / reject_ingest - Handle queued items

Claude Code Commands

Development

# Clone and setup
git clone https://github.com/nickperrott/videodrome-plugin.git
cd videodrome-plugin
uv sync --extra dev

# Run tests
pytest tests/ -v

# Run server locally
uv run videodrome

Plex Naming Conventions

Movies

/Movies/Movie Name (Year) {tmdb-ID}/Movie Name (Year) {tmdb-ID}.mkv

TV Shows

/TV Shows/Show Name (Year)/Season 01/Show Name (Year) - s01e01 - Episode Title.mkv

License

MIT