plex

This Plex MCP Server exposes a set of tools that let your AI assistant query and manage your Plex Media Server. It tokenizes Plex content into a structured, queryable interface, enabling capabilities like listing libraries, fetching library items with pagination, exporting libraries to JSON, retrieving detailed media metadata, and obtaining analytics and watch history. The server also offers Sonarr/Radarr and Trakt integrations (in specific configurations) to browse series/movies, trigger searches, sync watch history, and fetch related stats. To use it, configure the MCP client (e.g., Claude Desktop) to point at the Plex MCP server, providing your Plex URL and token as environment variables. Once configured, you can ask your AI assistant questions such as: What movies did I watch last week? Show me my most popular TV shows this month. Continue watching what's on my deck. List all Plex libraries. The tools available cover core Plex data access (libraries, items, playlists, watch history), metadata inspection, and a suite of analytics and cross-service integrations.

Prerequisites:

• Node.js 18+ installed on the host
• Plex Media Server running and accessible
• Plex token for authentication
• An MCP-compatible client (e.g., Claude Desktop)

Installation steps:

# 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

Configure environment and MCP client:

# Copy the example environment file (if provided) and edit with your details
# cp .env.example .env
# Edit .env with your Plex URL and token
# PLEX_URL=http://localhost:32400
# PLEX_TOKEN=your_plex_token_here

Configure MCP client (example for Plex only):

{
  "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"
      }
    }
  }
}

Run the server (example):

node build/index.js

Adjust the path to the built entry point as appropriate for your deployment.

Tips and caveats:

• Ensure your Plex URL and token are correctly set; missing keys will result in startup errors for tools that require authentication.
• If you enable Sonarr/Radarr or Trakt integrations, provide the appropriate API keys and URLs via the env block; keys are optional at startup for some tools but required for those features to function.
• The MCP client configuration uses the current server as a named entry (e.g., plex, plex-arr, plex-trakt). Use the exact server name you configured in MCP client settings.
• The standalone Plex tools include a core set of functions (get_libraries, get_library_items, export_library, search_media, get_recently_added, get_on_deck, get_media_details, get_editable_fields, get_playlists, get_playlist_items, get_watchlist, get_recently_watched, get_watch_history) plus additional stats when running the dedicated Plex server. If you enable additional integrations, more functions become available (e.g., for Sonarr/Radarr and Trakt).
• API keys and tokens are sensitive; store them securely and do not commit them to version control.
• If you encounter authentication errors, regenerate or re-verify your Plex token and ensure network access between the MCP host and Plex server.