Plex MCP Server

Prerequisites

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

Install dependencies

npm install

Requirements

• Node.js 20.0.0 or higher
• Plex Media Server (any recent version)
• Network access between MCP server and Plex server
• Valid Plex token with appropriate permissions

Installation

```bash

Build the project

npm run build

Or install directly from npm:

Build for production

npm run build

Building from Source

git clone https://github.com/niavasha/plex-mcp-server.git
cd plex-mcp-server
npm install
npm run dev

Quick Start

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 Night of the Living Dead in my library"
"What's on my continue watching list?"
"List all my Plex libraries"
"Add that new show to Sonarr"
"What's in my Radarr download queue?"
"Sync my Plex history to Trakt"

Development Guidelines

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Configuration

1. Get your Plex token (see instructions below)

1. Configure your MCP client (e.g., Claude Desktop):

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

        "SONARR_URL": "http://localhost:8989",
        "SONARR_API_KEY": "optional_sonarr_api_key",

        "RADARR_URL": "http://localhost:7878",
        "RADARR_API_KEY": "optional_radarr_api_key",

        "TRAKT_CLIENT_ID": "optional_trakt_client_id",
        "TRAKT_CLIENT_SECRET": "optional_trakt_client_secret"
      }
    }
  }
}

Only PLEX_TOKEN is required. All other credentials are optional — tools for unconfigured services return a clear error message explaining how to set them up, rather than crashing the server.

Sonarr/Radarr API keys can be found at Settings > General > API Key in each app's web UI.

Trakt.tv setup requires a Trakt OAuth application. Create one with redirect URI urn:ietf:wg:oauth:2.0:oob, then add the Client ID and Secret to your config. Once the server is running, ask your AI assistant to "authenticate with Trakt" — it will guide you through the OAuth flow. See the Trakt setup guide for detailed instructions.

<details> <summary><strong>Migrating from v1.0.x?</strong></summary>

In v1.0.x there were three separate server binaries (build/index.js, build/plex-trakt-server.js, build/plex-arr-server.js). In v1.1.0+ these are replaced by a single unified binary: build/plex-mcp-server.js.

The old binaries still work but emit a deprecation warning. Update your MCP config to point to build/plex-mcp-server.js and remove any duplicate server entries.

See the migration guide for full details. </details>

Recommended Workflows

Sync Plex watch history to Trakt: 1. Set up Trakt credentials (see above) 2. Ask: "Authenticate with Trakt" — follow the OAuth flow 3. Ask: "Do a dry run sync of my Plex history to Trakt" — preview what would sync 4. Ask: "Sync my Plex watch history to Trakt" — run the actual sync

Find and add new content: 1. Ask: "Search Sonarr for The Beverly Hillbillies" — find the TVDB ID 2. Ask: "Add The Beverly Hillbillies to Sonarr" — it auto-detects quality profiles and root folders 3. Ask: "What's in my Sonarr download queue?" — monitor progress

Get personalized recommendations: 1. Ask: "Recommend me some movies from my library" 2. The engine analyzes your watch history — genres, directors, actors, ratings 3. Scores every unwatched movie and returns the top matches with reasons 4. For multi-user servers, specify the user: "Recommend movies for Titus" 5. If Trakt is configured, it automatically uses your Trakt history too — catching movies you watched outside Plex (other platforms, before tracking was set up)

Cross-platform viewing analytics: 1. Ask: "Show me my Plex viewing stats for the last 30 days" 2. Ask: "What are my Trakt stats?" — see lifetime stats (movies watched, hours, milestones) 3. Ask: "What are my most popular movies this month?"

Troubleshooting