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

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)

Function	Description
get_libraries	List all Plex libraries
get_library_items	List items in a library with pagination
export_library	Export a full library to JSON (under ./exports)
search_media	Search media globally or within one library
get_recently_added	Recently added content; pass type and libraryKey to list e.g. new episodes (TV is otherwise grouped by season)
get_on_deck	Continue watching list
get_media_details	Detailed media info
get_editable_fields	Show editable fields, available tags and locked fields for an item
get_playlists	List all Plex playlists
get_playlist_items	List items in a playlist
get_watchlist	Get the current account Watchlist from Plex Discover
get_recently_watched	Recently watched content
get_watch_history	Detailed watch sessions
get_fully_watched	Fully watched movies/shows
get_watch_stats	Comprehensive viewing statistics
get_user_stats	User activity statistics
get_library_stats	Library usage metrics
get_popular_content	Most popular content analysis
get_recommendations	Personalized movie recommendations based on your watch history
get_active_sessions	Currently active Plex streams — who is watching what, player state, transcoding

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.

Function	Description
update_metadata	Update metadata fields and editable tags for a media item. A tag field is locked against refreshes while it holds tags; passing an empty list clears it and unlocks it
update_metadata_from_json	Apply a metadata JSON payload using best-effort field mapping
create_playlist	Create a new smart or static playlist
add_to_playlist	Add a media item to a playlist
remove_from_playlist	Remove an item from a playlist
clear_playlist	Preview and optionally clear all items from a playlist (confirm=true)
delete_playlist	Delete a playlist without deleting the underlying media
add_to_watchlist	Add a matched local movie or show to the account Watchlist
remove_from_watchlist	Remove an account Watchlist item by its global Plex GUID or local rating key
rate_media	Set the user's rating for a media item from 0 to 10
mark_watched	Mark a media item as watched
mark_unwatched	Mark a media item as unwatched

Sonarr Tools (12 tools)

Function	Description
sonarr_get_series	List series with optional title filter
sonarr_search	Search TheTVDB for new series
sonarr_add_series	Add series by TVDB ID, optionally with tags (created if missing)
sonarr_get_missing	Missing/wanted episodes
sonarr_get_queue	Download queue
sonarr_get_calendar	Upcoming episodes
sonarr_get_profiles	Quality profiles and root folders
sonarr_trigger_search	Trigger missing episode search
sonarr_get_tags	List tags with their IDs and labels
sonarr_create_tag	Create a tag
sonarr_update_tag	Rename a tag
sonarr_delete_tag	Delete a tag

Radarr Tools (12 tools)

Function	Description
radarr_get_movies	List movies with optional title filter
radarr_search	Search TMDB for new movies
radarr_add_movie	Add movie by TMDB ID, optionally with tags (created if missing)
radarr_get_missing	Missing/wanted movies
radarr_get_queue	Download queue
radarr_get_calendar	Upcoming movies
radarr_get_profiles	Quality profiles and root folders
radarr_trigger_search	Trigger missing movie search
radarr_get_tags	List tags with their IDs and labels
radarr_create_tag	Create a tag
radarr_update_tag	Rename a tag
radarr_delete_tag	Delete a tag

Cross-Service Tools (1 tool)

Function	Description
arr_get_status	Check Sonarr/Radarr connection status

Trakt Tools (9 tools)

Function	Description
trakt_authenticate	Start Trakt.tv OAuth flow
trakt_complete_auth	Complete authentication
trakt_get_auth_status	Check auth status
trakt_sync_to_trakt	Sync Plex history to Trakt
trakt_sync_from_trakt	Get Trakt data for comparison
trakt_get_user_stats	Enhanced stats from Trakt
trakt_search	Search Trakt database
trakt_start_scrobbling	Real-time scrobbling
trakt_get_sync_status	Check sync operation status

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