Plex MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with comprehensive access to your Plex Media Server. Query your libraries, get viewing statistics, and manage your media through natural language interactions.

<a href="https://glama.ai/mcp/servers/@niavasha/plex-mcp-server"> <img width="380" height="200" src="https://glama.ai/mcp/servers/@niavasha/plex-mcp-server/badge" alt="Plex Server MCP server" /> </a>

🎬 What is this?

This MCP server transforms your Plex Media Server into an AI-queryable database. Ask your AI assistant questions like:

• "What movies have I watched recently?"
• "Show me my viewing statistics for the past month"
• "What's the most popular content on my server?"
• "Find action movies in my library"
• "What's on my continue watching list?"

✨ Features

📚 Library Management (Plex)

• Browse all Plex libraries
• List library items with pagination and sorting controls
• Export full libraries to JSON without truncation
• Search across movies, TV shows, music, and more
• Restrict search to a specific library section
• Get detailed metadata for any media item

📄 Read-Only Metadata & Lists (Plex)

• Inspect editable fields and current tags for any media item
• List all playlists and items in a playlist
• Get Plex watchlist with fallback endpoint support

📊 Tautulli-Style Analytics (Plex)

• Comprehensive viewing statistics
• User activity tracking
• Popular content analysis
• Watch history with progress tracking
• Library usage metrics

🎯 Smart Querying (Plex)

• Recently watched content
• Fully watched movies/shows
• Continue watching (On Deck)
• Recently added media

📡 Sonarr/Radarr Integration (Plex+Arr Server)

• Browse and search your Sonarr series and Radarr movie libraries
• Add new series/movies by TVDB/TMDB ID with auto-detected quality profiles
• View download queues, missing episodes/movies, and calendar
• Trigger searches for missing content
• Check service status for both Sonarr and Radarr

🔄 Trakt.tv Sync (Plex+Trakt Server)

• OAuth authentication with Trakt.tv
• Sync Plex watch history to Trakt
• Enhanced viewing statistics from Trakt
• Search the Trakt database
• Real-time scrobbling support

🚀 Quick Start

Prerequisites

• Node.js 18+
• Plex Media Server (any recent version)
• Plex Token (How to get your token)
• MCP-compatible client (Claude Desktop, etc.)

Installation

# Clone the repository
git clone https://github.com/niavasha/plex-mcp-server.git
cd plex-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

Configuration

1. Get your Plex token (see instructions below)

2. Create environment file:

# Copy the example environment file
cp .env.example .env

# Edit with your details
PLEX_URL=http://localhost:32400
PLEX_TOKEN=your_plex_token_here
# Optional: enable mutative Plex tools (disabled by default)
# PLEX_ENABLE_MUTATIVE_OPS=true

3. Configure your MCP client:

Add to your MCP client configuration (e.g., Claude Desktop).

Plex only (18 tools):

{
  "mcpServers": {
    "plex": {
      "command": "node",
      "args": ["/path/to/plex-mcp-server/build/index.js"],
      "env": {
        "PLEX_URL": "http://localhost:32400",
        "PLEX_TOKEN": "your_plex_token_here",
        "PLEX_ENABLE_MUTATIVE_OPS": "true"
      }
    }
  }
}

Plex + Sonarr/Radarr (30 tools):

{
  "mcpServers": {
    "plex-arr": {
      "command": "node",
      "args": ["/path/to/plex-mcp-server/build/plex-arr-server.js"],
      "env": {
        "PLEX_URL": "http://localhost:32400",
        "PLEX_TOKEN": "your_plex_token_here",
        "SONARR_URL": "http://localhost:8989",
        "SONARR_API_KEY": "your_sonarr_api_key",
        "RADARR_URL": "http://localhost:7878",
        "RADARR_API_KEY": "your_radarr_api_key"
      }
    }
  }
}

Plex + Trakt.tv (22 tools):

{
  "mcpServers": {
    "plex-trakt": {
      "command": "node",
      "args": ["/path/to/plex-mcp-server/build/plex-trakt-server.js"],
      "env": {
        "PLEX_URL": "http://localhost:32400",
        "PLEX_TOKEN": "your_plex_token_here",
        "TRAKT_CLIENT_ID": "your_trakt_client_id",
        "TRAKT_CLIENT_SECRET": "your_trakt_client_secret"
      }
    }
  }
}

Note: Sonarr/Radarr API keys are optional at startup — tools that need them will return a helpful error message if the key is missing. Find your API keys at Settings > General > API Key in each app's web UI.

Usage

Once configured, you can ask your AI assistant:

🎬 "What movies did I watch last week?"
📺 "Show me my most popular TV shows this month"
📊 "Give me viewing statistics for the past 30 days"
🔍 "Search for Christopher Nolan movies in my library"
▶️ "What's on my continue watching list?"
📚 "List all my Plex libraries"

🛠️ Available Functions

Plex Tools (all servers)

| Function | Description | |----------|-------------| | get_libraries | List all Plex libraries | | get_library_items | List items in a library with pagination | | export_library | Export a full library to JSON (under ./exports) | | search_media | Search media globally or within one library | | get_recently_added | Recently added content | | get_on_deck | Continue watching list | | get_media_details | Detailed media info | | get_editable_fields | Show editable fields and available tags for an item | | get_playlists | List all Plex playlists | | get_playlist_items | List items in a playlist | | get_watchlist | Get current Plex watchlist | | get_recently_watched | Recently watched content | | get_watch_history | Detailed watch sessions |

The standalone Plex server also includes: get_fully_watched, get_watch_stats, get_user_stats, get_library_stats, get_popular_content.

Mutative Plex Tools (PLEX_ENABLE_MUTATIVE_OPS=true)

| Function | Description | |----------|-------------| | update_metadata | Update metadata fields and editable tags for a media item | | update_metadata_from_json | Apply a metadata JSON payload using best-effort field mapping | | create_playlist | Create a new smart or static playlist | | add_to_playlist | Add a media item to a playlist | | remove_from_playlist | Remove an item from a playlist | | clear_playlist | Preview and optionally clear all items from a playlist (confirm=true) | | delete_playlist | Delete a playlist without deleting the underlying media | | add_to_watchlist | Add a media item to the Plex watchlist | | remove_from_watchlist | Remove a media item from the Plex watchlist |

Sonarr Tools (plex-arr-server)

| Function | Description | |----------|-------------| | sonarr_get_series | List series with optional title filter | | sonarr_search | Search TheTVDB for new series | | sonarr_add_series | Add series by TVDB ID | | sonarr_get_missing | Missing/wanted episodes | | sonarr_get_queue | Download queue | | sonarr_get_calendar | Upcoming episodes | | sonarr_get_profiles | Quality profiles and root folders | | sonarr_trigger_search | Trigger missing episode search |

Radarr Tools (plex-arr-server)

| Function | Description | |----------|-------------| | radarr_get_movies | List movies with optional title filter | | radarr_search | Search TMDB for new movies | | radarr_add_movie | Add movie by TMDB ID | | radarr_get_missing | Missing/wanted movies | | radarr_get_queue | Download queue | | radarr_get_calendar | Upcoming movies | | radarr_get_profiles | Quality profiles and root folders | | radarr_trigger_search | Trigger missing movie search |

Cross-Service Tools (plex-arr-server)

| Function | Description | |----------|-------------| | arr_get_status | Check Sonarr/Radarr connection status |

Trakt Tools (plex-trakt-server)

| Function | Description | |----------|-------------| | trakt_authenticate | Start Trakt.tv OAuth flow | | trakt_complete_auth | Complete authentication | | trakt_get_auth_status | Check auth status | | trakt_sync_to_trakt | Sync Plex history to Trakt | | trakt_sync_from_trakt | Get Trakt data for comparison | | trakt_get_user_stats | Enhanced stats from Trakt | | trakt_search | Search Trakt database | | trakt_start_scrobbling | Real-time scrobbling | | trakt_get_sync_status | Check sync operation status |

🔑 Getting Your Plex Token

1. Open Plex Web App in your browser
2. Navigate to Settings → Account → Privacy
3. Click "Show Advanced" at the bottom
4. Copy your Plex Token

Alternative method:

• Visit: http://YOUR_PLEX_IP:32400/web/index.html#!/settings/account
• Look for the "Plex Token" field

📁 Project Structure

plex-mcp-server/
├── src/
│   ├── index.ts               # Standalone Plex server (18 tools)
│   ├── plex-arr-server.ts     # Plex + Sonarr/Radarr server (30 tools)
│   ├── plex-trakt-server.ts   # Plex + Trakt server (22 tools)
│   ├── plex/                  # Shared Plex module
│   │   ├── client.ts          #   Plex API client
│   │   ├── tools.ts           #   Plex tool implementations
│   │   ├── tool-registry.ts   #   Map-based tool dispatch
│   │   ├── tool-schemas.ts    #   MCP tool schema definitions
│   │   ├── constants.ts       #   Configuration defaults
│   │   └── types.ts           #   TypeScript type definitions
│   ├── arr/                   # Sonarr/Radarr module
│   │   ├── clien