A Model Context Protocol (MCP) server that provides programmatic access to Plex Media Server functionality. This server exposes Plex's extensive media management, playback, and library capabilities as MCP tools that can be used by AI assistants and other MCP clients.
- Library Management: Browse libraries, get media metadata, and manage collections
- Search: Search across all libraries or within specific sections
- Playback Control: View active sessions and update playback timeline
- User Watch History: Track user viewing patterns and analyze watch statistics
- Personalized Recommendations: Build recommendation systems based on user preferences
- Playlists: Create, manage, and interact with playlists
- Content Discovery: Get recommendations, hubs, recently added content, and continue watching
- Watch Status: Mark items as watched/unwatched and rate content
- Docker Support: Deploy easily with Docker and Portainer
- Robust Error Handling: Comprehensive error handling with meaningful error messages
- Type Safety: Full TypeScript implementation with strict type checking
- Node.js 18.0.0 or higher (for local installation)
- OR Docker (for containerized deployment)
- A running Plex Media Server
- Plex authentication token
Deploy using Docker and Portainer for easy management:
See PORTAINER_DEPLOYMENT.md for detailed Portainer deployment instructions.
Quick start with Docker Compose:
# Clone the repository
git clone https://github.com/Jamdries/plex-mcp
cd plex-mcp
# Copy environment template
cp .env.example .env
# Edit .env with your Plex credentials
nano .env
# Build and run with Docker Compose
docker-compose up -d- Clone the repository:
git clone <repository-url>
cd plex-mcp-server- Install dependencies:
npm install- Build the project:
npm run buildThe server can be configured using environment variables or a configuration file.
Create a .env file in the project root:
PLEX_SERVER_URL=https://192-168-1-100.abc123def456.plex.direct:32400
PLEX_TOKEN=your_plex_token_here
PLEX_TIMEOUT=30000
PLEX_VALIDATE_SSL=trueCreate a plex-config.json file:
{
"plexServerUrl": "https://192-168-1-100.abc123def456.plex.direct:32400",
"plexToken": "your_plex_token_here",
"timeout": 30000,
"validateSSL": true
}To get your Plex authentication token:
- Sign in to Plex Web App
- Open any media item
- Click the three dots menu → "Get Info"
- Click "View XML"
- Look for
X-Plex-Tokenin the URL
For more details, see the official Plex documentation.
Your Plex server URL typically follows this pattern:
https://{IP-description}.{identifier}.plex.direct:{port}
Example: https://192-168-1-100.abc123def456.plex.direct:32400
You can find this in:
- Plex Web App → Settings → Network → Server URLs
- Or use
http://localhost:32400if running on the same machine
npm startOr for development with auto-reload:
npm run devAdd to your Claude Desktop configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"plex": {
"command": "node",
"args": ["/path/to/plex-mcp-server/dist/index.js"],
"env": {
"PLEX_SERVER_URL": "https://192-168-1-100.abc123def456.plex.direct:32400",
"PLEX_TOKEN": "your_plex_token_here"
}
}
}
}- get_server_info: Get Plex Media Server information and identity
- list_libraries: Get all library sections
- get_library_items: Get all items in a library section
- get_item_metadata: Get detailed metadata for a specific item
- search_media: Search across all libraries
- search_library: Search within a specific library section
- get_sessions: Get active playback sessions
- update_timeline: Update playback position/state for a media item
- get_recently_added: Get recently added media items
- get_on_deck: Get on deck items (continue watching)
- list_playlists: Get all playlists
- get_playlist_items: Get items in a playlist
- create_playlist: Create a new playlist
- add_to_playlist: Add items to a playlist
- list_collections: Get collections in a library section
- get_collection_items: Get items in a collection
- mark_watched: Mark an item as watched (scrobble)
- mark_unwatched: Mark an item as unwatched (unscrobble)
- rate_item: Rate a media item (0-10)
- get_hubs: Get all content hubs (recommendations)
- get_accounts: Get all user accounts on the server
- get_session_history: Get complete watch history with optional filters (accountID, librarySectionID, ratingKey, mindate)
- get_user_watch_history: Get watch history for a specific user
- get_user_watch_statistics: Get detailed watch statistics and preferences for a user (includes most watched items, recent history, and total watches)
Once configured with an MCP client like Claude Desktop, you can interact with your Plex server using natural language:
General Queries:
- "What movies are in my Plex library?"
- "Search for 'The Matrix' in my Plex server"
- "What am I currently watching on Plex?"
- "Show me recently added content"
- "Create a playlist called 'Favorites'"
- "Mark episode 5 as watched"
User Watch History & Recommendations:
- "Who are all the users on my Plex server?"
- "What has user ID 12345 been watching?"
- "Show me the most watched shows by user John"
- "What are user Jane's viewing preferences?"
- "Recommend similar shows based on what user Bob watches"
- "Get watch statistics for all users"
plex-mcp-server/
├── src/
│ ├── index.ts # Main MCP server entry point
│ ├── plex-client.ts # Plex API client wrapper
│ ├── types.ts # TypeScript type definitions
│ └── config.ts # Configuration management
├── openapi.json # OpenAPI specification (reference)
├── package.json
├── tsconfig.json
└── README.md
npm run build- Build TypeScript to JavaScriptnpm run watch- Watch mode for developmentnpm run dev- Run in development mode with tsxnpm start- Run the built server
The server includes comprehensive error handling for:
- Network errors (timeout, connection refused)
- Authentication errors (401, 403)
- Not found errors (404)
- Server errors (500+)
- Rate limiting (429)
- Invalid parameters
All errors are returned with meaningful error messages to help diagnose issues.
- Store your Plex token securely
- Use environment variables or secure configuration files
- Don't commit tokens to version control
- Consider using SSL validation in production (
validateSSL: true) - Limit server access using Plex's built-in security features
- Verify the server URL is correct
- Check that the Plex server is running
- Ensure network connectivity to the server
- Verify firewall rules allow the connection
- Check that your Plex token is valid
- Ensure the token has appropriate permissions
- Try regenerating the token from Plex Web App
- If using self-signed certificates, set
validateSSL: false - For production, use proper SSL certificates
This MCP server implements the most commonly used Plex API endpoints:
- Server Information: Identity, status, capabilities
- Library Management: Sections, items, metadata
- Search: Global and section-specific search
- Playback: Sessions, timeline updates
- Playlists: CRUD operations
- Collections: Browse and manage collections
- Watch Status: Scrobble/unscrobble, ratings
- Content Discovery: Hubs, recommendations
For the complete Plex API specification, see openapi.json.
Apache 2.0
Contributions are welcome! Please feel free to submit issues or pull requests.
For issues and questions:
- Check the troubleshooting section
- Review the Plex API documentation
- Open an issue on GitHub