README.md•6.11 kB
# Plex MCP Server
[](https://smithery.ai/server/@djbriane/plex-mcp)
This is a Python-based MCP server that integrates with the Plex Media Server API to search for movies and manage playlists. It uses the PlexAPI library for seamless interaction with your Plex server.
## Screenshots
Here are some examples of how the Plex MCP server works:
### 1. Find Movies in Plex Library by Director
Search for movies in your Plex library by specifying a director's name. For example, searching for "Alfred Hitchcock" returns a list of his movies in your library.
---
### 2. Find Missing Movies for a Director
Identify movies by a specific director that are missing from your Plex library. This helps you discover gaps in your collection.
---
### 3. Create a Playlist in Your Plex Library
Create a new playlist in your Plex library using the movies found in a search. This allows you to organize your library efficiently.
## Setup
### Prerequisites
- Python 3.8 or higher
- `uv` package manager
- A Plex Media Server with API access
### Installation
### Installing via Smithery
To install Plex Media Server Integration for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@djbriane/plex-mcp):
```bash
npx -y @smithery/cli install @djbriane/plex-mcp --client claude
```
### Installing Manually
1. Clone this repository:
```
git clone <repository-url>
cd plex-mcp
```
2. Install dependencies with `uv`:
```
uv venv
source .venv/bin/activate
uv sync
```
3. Configure environment variables for your Plex server:
- `PLEX_TOKEN`: Your Plex authentication token
- `PLEX_SERVER_URL`: Your Plex server URL (e.g., http://192.168.1.100:32400)
### Finding Your Plex Token
You can find your Plex token in this way:
- Sign in to Plex Web App
- Open Developer Tools
- In Console tab, paste and run:
```javascript
window.localStorage.getItem('myPlexAccessToken')
```
## Usage with Claude
Add the following configuration to your Claude app:
```json
{
"mcpServers": {
"plex": {
"command": "uv",
"args": [
"--directory",
"FULL_PATH_TO_PROJECT",
"run",
"src/plex_mcp/plex_mcp.py"
],
"env": {
"PLEX_TOKEN": "YOUR_PLEX_TOKEN",
"PLEX_SERVER_URL": "YOUR_PLEX_SERVER_URL"
}
}
}
}
```
## Available Commands
The Plex MCP server exposes these commands:
| Command | Description | OpenAPI Reference |
|----------------------|-----------------------------------------------------------------------------|---------------------------------------|
| `search_movies` | Search for movies in your library by various filters (e.g., title, director, genre) with support for a `limit` parameter to control the number of results. | `/library/sections/{sectionKey}/search` |
| `get_movie_details` | Get detailed information about a specific movie. | `/library/metadata/{ratingKey}` |
| `get_movie_genres` | Get the genres for a specific movie. | `/library/sections/{sectionKey}/genre` |
| `list_playlists` | List all playlists on your Plex server. | `/playlists` |
| `get_playlist_items` | Get the items in a specific playlist. | `/playlists/{playlistID}/items` |
| `create_playlist` | Create a new playlist with specified movies. | `/playlists` |
| `delete_playlist` | Delete a playlist from your Plex server. | `/playlists/{playlistID}` |
| `add_to_playlist` | Add a movie to an existing playlist. | `/playlists/{playlistID}/items` |
| `recent_movies` | Get recently added movies from your library. | `/library/recentlyAdded` |
## Running Tests
This project includes both unit tests and integration tests. Use the following instructions to run each type of test:
### Unit Tests
Unit tests use dummy data to verify the functionality of each module without requiring a live Plex server.
To run all unit tests:
```bash
uv run pytest
```
### Integration Tests
Integration tests run against a live Plex server using environment variables defined in a .env file. First, create a .env file in your project root with your Plex configuration:
```env
PLEX_SERVER_URL=https://your-plex-server-url:32400
PLEX_TOKEN=yourPlexTokenHere
```
Integration tests are marked with the integration marker. To run only the integration tests:
```bash
uv run pytest -m integration
```
If you are experiencing connection issues to your Plex server try running the integration tests to help troubleshoot.
## Code Style and Conventions
- **Module Structure:**
Use clear section headers for imports, logging setup, utility functions, class definitions, global helpers, tool methods, and main execution (guarded by `if __name__ == "__main__":`).
- **Naming:**
Use CamelCase for classes and lower_snake_case for functions, variables, and fixtures. In tests, list built-in fixtures (e.g. `monkeypatch`) before custom ones.
- **Documentation & Comments:**
Include a concise docstring for every module, class, and function, with in-line comments for complex logic.
- **Error Handling & Logging:**
Use Python’s `logging` module with consistent error messages (prefix “ERROR:”) and explicit exception handling.
- **Asynchronous Patterns:**
Define I/O-bound functions as async and use `asyncio.to_thread()` to handle blocking operations.