Plex

You turn Plex into an AI-queryable data source by running an MCP server that connects to your Plex Media Server and optional Sonarr, Radarr, or Trakt integrations. This enables natural language interactions to explore libraries, view statistics, manage media, and trigger actions across your Plex ecosystem with ease.

How to use

Start by configuring your MCP clients to point to the Plex MCP Server variants you run locally. Once connected, you can ask your AI assistant to list libraries, show viewing statistics, search your collection, or fetch detailed media information. You can also enable optional integrations like Sonarr/Radarr or Trakt to extend capabilities, such as managing series and movies, syncing watch history, and performing cross-service searches.

How to install

Prerequisites you must have before installing the Plex MCP Server are present on your system.

# Step 1: Install Node.js (18+)
# Step 2: Clone the repository
git clone https://github.com/niavasha/plex-mcp-server.git
cd plex-mcp-server

# Step 3: Install dependencies
npm install

# Step 4: Build the project
npm run build

# Step 5: Run the standalone Plex MCP server (Plex only)
npm start

# Optional: Start the Plex + Sonarr/Radarr MCP server
# Ensure you have the required environment variables set, then run the corresponding start command

Configuration and usage notes

Configure your environment with the Plex URL and your Plex token. You can also enable optional integrations by providing their URLs and API keys when you start the respective MCP servers.

# 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 + 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"
      }
    }
  }
}

Security and maintenance

Keep your Plex token secure and avoid committing it to version control. Use environment variables for sensitive configuration and run the MCP server on trusted networks since it communicates directly with Plex.

Troubleshooting

If you encounter issues, verify that the Plex URL and token are correct, ensure the MCP server can reach Plex, and check that any optional service keys are provided when required.

Development and contribution

If you want to extend or customize the MCP server, install dependencies, build, and run the relevant server variant following the steps above. Contributions are welcome.

Available tools

get_libraries

List all Plex libraries and their metadata.

get_library_items

List items in a library with pagination and sorting.

export_library

Export an entire library to JSON for external use.

search_media

Search media globally or within a specific library.

get_recently_added

Show content recently added to your Plex libraries.

get_on_deck

Return the current continue-watching list.

get_media_details

Fetch detailed metadata for a media item.

get_editable_fields

Show editable fields and current tags for a media item.

get_playlists

List all Plex playlists.

get_playlist_items

List items in a playlist.

get_watchlist

Retrieve your Plex watchlist.

get_recently_watched

Show content you recently watched.

get_watch_history

Provide detailed watch sessions history.

get_fully_watched

Identify fully watched items in your library.

get_watch_stats

Provide viewing statistics similar to analytics dashboards.

get_user_stats

Show per-user viewing statistics.

get_library_stats

Provide statistics for each library.

get_popular_content

Analyze and return the most popular items.

sonarr_get_series

List Sonarr series with optional title filter.

sonarr_search

Search TheTVDB for new series to add.

sonarr_add_series

Add a Sonarr series by TVDB ID.

sonarr_get_missing

Show missing or wanted episodes.

sonarr_get_queue

Display the Sonarr download queue.

sonarr_get_calendar

Show upcoming episodes in Sonarr.

sonarr_get_profiles

List Sonarr quality profiles and root folders.

sonarr_trigger_search

Trigger a search for missing episodes.

radarr_get_movies

List Radarr movies with optional title filter.

radarr_search

Search TMDB for new movies.

radarr_add_movie

Add a Radarr movie by TMDB ID.

radarr_get_missing

Show missing or wanted movies.

radarr_get_queue

Display the Radarr download queue.

radarr_get_calendar

Show upcoming movies in Radarr.

radarr_get_profiles

List Radarr quality profiles and root folders.

radarr_trigger_search

Trigger a search for missing movies.

arr_get_status

Check Sonarr/Radarr connection status.

trakt_authenticate

Start Trakt.tv OAuth flow.

trakt_complete_auth

Complete authentication with Trakt.

trakt_get_auth_status

Check Trakt authentication status.

trakt_sync_to_trakt

Sync Plex history to Trakt.

trakt_sync_from_trakt

Get Trakt data for comparison.

trakt_get_user_stats

Get enhanced stats from Trakt.

trakt_search

Search the Trakt database.

trakt_start_scrobbling

Enable real-time scrobbling to Trakt.

trakt_get_sync_status

Check status of Trakt sync operations.