Plex MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with comprehensive access to your Plex Media Server, Sonarr, Radarr, and Trakt.tv — all from a single unified server.

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?"

• "Add that new show to Sonarr"

• "What's in my download queue?"

• "Sync my watch history to Trakt"

• "Recommend me some movies I haven't seen"

Related MCP server: YARR Media Stack MCP Server

Features

54 tools out of the box (66 with write operations enabled):

• Plex Library Management — Browse libraries, search media, get detailed metadata, list playlists and watchlist

• Tautulli-Style Analytics — Viewing statistics, user activity, popular content, watch history

• Personalized Recommendations — AI-powered movie suggestions based on your watch history, genres, directors, and actors. Supports per-user profiles for multi-user Plex servers.

• Sonarr/Radarr Integration — Browse, search, add series/movies, view queues, trigger downloads

• Trakt.tv Sync — OAuth authentication, watch history sync, enhanced statistics, scrobbling. When configured, Trakt data enriches recommendations by catching movies watched outside Plex.

• Write Operations (opt-in) — Create/edit playlists, update metadata, manage watchlist, rate media, and mark media watched or unwatched

One server, all tools. Trakt and Sonarr/Radarr credentials are optional — tools that need them return a helpful setup message if the key is missing. You don't need to configure everything upfront.

Quick Start

Prerequisites

• Node.js 20+

• 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

Or install directly from npm:

npx plex-mcp-server

Run with Docker

Each release from the next one onwards is published to GitHub Container Registry for linux/amd64 and linux/arm64, tagged with its full version (X.Y.Z), X.Y, X and latest.

The image starts the HTTP transport on port 3000, serving MCP at /mcp:

docker run -d --name plex-mcp \
  -e PLEX_URL=http://your-plex-host:32400 \
  -e PLEX_TOKEN=your_plex_token \
  -p 127.0.0.1:3000:3000 \
  ghcr.io/niavasha/plex-mcp-server:latest

The HTTP endpoint has no authentication of its own, and anyone who can reach it can call tools that use your Plex token. Keep it bound to 127.0.0.1 as above, or behind something that authenticates. Set MCP_PORT to listen on a different port, and MCP_PATH to serve MCP somewhere other than /mcp (for example /plex/mcp behind a reverse proxy). Outside Docker, the --port and --path flags do the same. The health check stays at /health.

For an MCP client that launches the server itself over stdio, override the command. --no-healthcheck turns off the image's HTTP health check, which a stdio container never answers:

docker run -i --rm --no-healthcheck \
  -e PLEX_URL=http://your-plex-host:32400 \
  -e PLEX_TOKEN=your_plex_token \
  ghcr.io/niavasha/plex-mcp-server:latest --transport stdio

The optional Trakt, Sonarr and Radarr variables from Configuration are passed the same way, with -e.

Configuration

1. Get your Plex token (see instructions below)

2. 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.

Compact Responses (optional)

Tools answer with JSON by default. Setting PLEX_OUTPUT_FORMAT=toon switches them to TOON, which writes an array of records once as a header and then as rows instead of repeating every field name on every record:

results[3]{ratingKey,title,year}:
  1001,Arrival,2016
  1002,Sicario,2015
  1003,Dune,2021

That is the same data your assistant would have received, in fewer characters. The saving is largest on long, uniform lists such as search_media, get_library_items and radarr_get_movies, and fewer characters usually means fewer tokens, though the exact effect depends on the payload and on your model's tokeniser. Each response is emitted as TOON only when it is shorter, in characters, than the same data as compact (minified) JSON, and as the usual JSON otherwise. Enabling this cannot make a response longer, in characters, than it is today. The guarantee is over characters, not tokens.

"env": {
  "PLEX_TOKEN": "your_plex_token_here",
  "PLEX_OUTPUT_FORMAT": "toon"
}

Leave the variable unset — the default — and responses are byte-for-byte the JSON they have always been.

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.

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"

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?"

Available Functions

54 tools out of the box (66 with write operations enabled).

Plex Tools (20 tools)

Write Operations (12 tools, opt-in)

Set PLEX_ENABLE_MUTATIVE_OPS=true to enable these tools. They allow your AI assistant to make changes to your Plex server. Use with care — while we test these tools, there are no guarantees. Review changes your assistant proposes before confirming.

Sonarr Tools (12 tools)

Radarr Tools (12 tools)

Cross-Service Tools (1 tool)

Trakt Tools (9 tools)

Getting Your Plex Token

Follow the official Plex instructions from Finding an authentication token / X-Plex-Token to obtain your token:

1. Sign in to your Plex account in the Plex Web App.

2. Browse to any media item in your library (a movie, TV show episode, music track, etc.).

3. Open Media Info:

   • Click the ... (More) menu on the item details page or poster card.

   • Select Get Info.

4. View the XML:

   • Click View XML at the bottom of the Media Info window.

5. Copy the Token:

   • In the new browser tab showing the XML, inspect the URL in the address bar.

   • Locate X-Plex-Token= in the URL parameters.

   • Copy the token string immediately following X-Plex-Token=.

6. Use this value for PLEX_TOKEN in your environment or MCP client configuration.

Note: Plex describes a token found this way as valid only temporarily. If the server starts failing to authenticate, repeat these steps to get a fresh token.

Project Structure

plex-mcp-server/
├── src/
│   ├── plex-mcp-server.ts    # Unified server entry point (44+ tools)
│   ├── index.ts               # Deprecated shim → plex-mcp-server
│   ├── plex-arr-server.ts     # Deprecated shim → plex-mcp-server
│   ├── plex-trakt-server.ts   # Deprecated shim → plex-mcp-server
│   ├── 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
│   │   ├── client.ts          #   Base ArrClient + Sonarr/Radarr subclasses
│   │   ├── mcp-functions.ts   #   Tool implementations (25 tools)
│   │   ├── tool-registry.ts   #   Map-based tool dispatch
│   │   ├── tool-schemas.ts    #   MCP tool schema definitions
│   │   ├── constants.ts       #   Configuration defaults
│   │   └── types.ts           #   TypeScript type definitions
│   ├── trakt/                 # Trakt.tv module
│   │   ├── client.ts          #   Trakt API client + OAuth
│   │   ├── sync.ts            #   Plex-to-Trakt sync engine
│   │   ├── mapper.ts          #   Plex-to-Trakt data mapping
│   │   ├── mcp-functions.ts   #   Tool implementations (9 tools)
│   │   ├── tool-registry.ts   #   Map-based tool dispatch
│   │   └── tool-schemas.ts    #   MCP tool schema definitions
│   ├── shared/                # Shared utilities
│   │   └── utils.ts           #   truncate, sleep, chunkArray
│   └── __tests__/             # Test suite (94 tests)
├── build/                     # Compiled JavaScript output
├── docs/                      # Documentation
├── package.json
├── tsconfig.json
├── vitest.config.ts
├── .env.example               # Environment variables template
└── README.md

Development

Scripts

# Development mode with auto-reload
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Run tests
npm test
npm run test:watch

Building from Source

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

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Merged contributors are credited in CONTRIBUTORS.md. Please use Conventional Commits — releases and the changelog are generated from them, see docs/RELEASING.md.

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

Troubleshooting

Common Issues

Connection refused:

• Verify your Plex server is running

• Check the PLEX_URL in your environment config

• Ensure the port (usually 32400) is correct

Host unreachable (EHOSTUNREACH / connect errors) on macOS:

• On macOS Sequoia, Sonoma, or later, connections to local IP addresses (like 10.0.0.10 or 192.168.1.50) may be blocked by Local Network Privacy settings.

• Workaround 1: Try connecting using the local hostname (e.g., plex.local or your Plex server name) rather than the direct IP address. Alternatively, use a Plex *.plex.direct domain.

• Workaround 2: Go to System Settings -> Privacy & Security -> Local Network on your Mac and ensure that the MCP client (e.g., Claude Desktop, Terminal, or VS Code) is enabled and has permission to access the local network.

Authentication errors:

• Verify your Plex token is correct

• Check token permissions in Plex settings

• Ensure token hasn't expired

Empty responses:

• Some features require Plex Pass

• Check if your libraries are accessible

• Verify media has been scanned and is available

Sonarr/Radarr connection issues:

• Verify Sonarr/Radarr is running and accessible from the MCP server host

• Check that the API key is correct (Settings > General > API Key)

• Sonarr uses API v3 at /api/v3/ — ensure your URL doesn't include a trailing path

• For large Radarr libraries (20k+ movies), the initial radarr_get_movies call may take up to 30 seconds

Trakt authentication issues:

• Ensure TRAKT_CLIENT_ID and TRAKT_CLIENT_SECRET are both set

• Use the trakt_authenticate tool to start the OAuth flow

• Complete authentication with trakt_complete_auth using the code from Trakt

MCP client issues:

• Ensure the path is set to build/plex-mcp-server.js (the unified server)

• Check that Node.js is in your system PATH

• Verify environment variables are set in client config

Getting Help

• Open an issue

• Check existing discussions

• Review the MCP documentation

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

Security Notes

• Keep your Plex token secure - never commit it to version control

• Use environment variables for sensitive configuration

• Run on trusted networks - the server communicates directly with Plex

• Regular token rotation - consider refreshing tokens periodically

• Write operations are disabled by default — enable only if you trust your AI assistant's judgment

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Everyone who has contributed code — this project is not a solo effort

• Anthropic for the Model Context Protocol

• Plex for the amazing media server

• Tautulli for analytics inspiration

• The open-source community for various libraries and tools

Related Projects

• Model Context Protocol - The standard this server implements

• Claude Desktop - Popular MCP client

• Tautulli - Plex monitoring and analytics

• PlexAPI - Python Plex API library

Built with love for the Plex and AI community