Content
# Plex MCP Server
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.
## Features
- **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
## Prerequisites
- Node.js 18.0.0 or higher (for local installation)
- OR Docker (for containerized deployment)
- A running Plex Media Server
- Plex authentication token
## Installation
### Option 1: Docker Deployment (Recommended)
Deploy using Docker and Portainer for easy management:
**See [PORTAINER_DEPLOYMENT.md](PORTAINER_DEPLOYMENT.md) for detailed Portainer deployment instructions.**
Quick start with Docker Compose:
```bash
# 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
```
### Option 2: Local Installation
1. Clone the repository:
```bash
git clone <repository-url>
cd plex-mcp-server
```
2. Install dependencies:
```bash
npm install
```
3. Build the project:
```bash
npm run build
```
## Configuration
The server can be configured using environment variables or a configuration file.
### Option 1: Environment Variables
Create a `.env` file in the project root:
```env
PLEX_SERVER_URL=https://192-168-1-100.abc123def456.plex.direct:32400
PLEX_TOKEN=your_plex_token_here
PLEX_TIMEOUT=30000
PLEX_VALIDATE_SSL=true
```
### Option 2: Configuration File
Create a `plex-config.json` file:
```json
{
"plexServerUrl": "https://192-168-1-100.abc123def456.plex.direct:32400",
"plexToken": "your_plex_token_here",
"timeout": 30000,
"validateSSL": true
}
```
### Getting Your Plex Token
To get your Plex authentication token:
1. Sign in to [Plex Web App](https://app.plex.tv/)
2. Open any media item
3. Click the three dots menu → "Get Info"
4. Click "View XML"
5. Look for `X-Plex-Token` in the URL
For more details, see the [official Plex documentation](https://support.plex.tv/articles/204059436-finding-an-authentication-token-x-plex-token/).
### Finding Your Plex Server URL
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:32400` if running on the same machine
## Usage
### Running the Server
```bash
npm start
```
Or for development with auto-reload:
```bash
npm run dev
```
### Using with Claude Desktop
Add to your Claude Desktop configuration file:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```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"
}
}
}
}
```
## Available Tools
### Server Information
- **get_server_info**: Get Plex Media Server information and identity
### Library Management
- **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
- **search_media**: Search across all libraries
- **search_library**: Search within a specific library section
### Playback & Sessions
- **get_sessions**: Get active playback sessions
- **update_timeline**: Update playback position/state for a media item
- **get_recently_added**: Get recently added media items
### Continue Watching
- **get_on_deck**: Get on deck items (continue watching)
### Playlists
- **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
### Collections
- **list_collections**: Get collections in a library section
- **get_collection_items**: Get items in a collection
### Watch Status
- **mark_watched**: Mark an item as watched (scrobble)
- **mark_unwatched**: Mark an item as unwatched (unscrobble)
### Ratings
- **rate_item**: Rate a media item (0-10)
### Content Discovery
- **get_hubs**: Get all content hubs (recommendations)
### User Management & Watch History
- **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)
## Example Usage
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"
## Development
### Project Structure
```
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
```
### Build Commands
- `npm run build` - Build TypeScript to JavaScript
- `npm run watch` - Watch mode for development
- `npm run dev` - Run in development mode with tsx
- `npm start` - Run the built server
## Error Handling
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.
## Security Considerations
- 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
## Troubleshooting
### Cannot connect to Plex server
- 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
### Authentication failed
- Check that your Plex token is valid
- Ensure the token has appropriate permissions
- Try regenerating the token from Plex Web App
### SSL/TLS errors
- If using self-signed certificates, set `validateSSL: false`
- For production, use proper SSL certificates
## API Coverage
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`.
## License
Apache 2.0
## Resources
- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
- [Plex API Documentation](https://www.plexopenapispec.com/)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
## Contributing
Contributions are welcome! Please feel free to submit issues or pull requests.
## Support
For issues and questions:
- Check the [troubleshooting section](#troubleshooting)
- Review the [Plex API documentation](https://www.plexopenapispec.com/)
- Open an issue on GitHub
