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

Features

46 tools out of the box (58 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

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 tokens —

around a third fewer across a spread of tool responses, and 40–60% fewer on the

list-shaped ones like `search_media`, `get_library_items` and `radarr_get_movies`.

The saving is only worth having on long lists, so each response is emitted as

TOON only when TOON is actually shorter, and as JSON otherwise; enabling this

cannot make a response larger than it is today.

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

Migrating from v1.0.x?

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

46 tools out of the box (58 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 (8 tools)

Radarr Tools (8 tools)

Cross-Service Tools (1 tool)

Trakt Tools (9 tools)

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/
│   ├── 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 (17 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