Plex MCP Server

A Model Context Protocol (MCP) server for Plex media management, enabling AI assistants like Claude to interact with your Plex library.

Features

• Movie Management: Search, browse, and analyze your movie collection
• Library Statistics: Get insights into your media collection
• Genre & Director Search: Find content by specific criteria
• Recent Additions: Track newly added content
• Extensible Architecture: Easy to add TV shows and other media types

Requirements

• Python 3.8 or higher
• Plex Media Server with accessible API
• Network access to your Plex server

Setup

Quick Setup (Recommended)

# Clone the repository
git clone https://github.com/richarddas/plex_mcp_server.git
cd plex_mcp_server

# Run the setup script (creates venv and installs dependencies)
./setup.sh

# Edit your Plex details
nano .env

# Activate virtual environment and start the server
source venv/bin/activate
python main.py

Manual Setup

1. Create and activate virtual environment:

python3 -m venv venv
   source venv/bin/activate

2. Install dependencies:

pip install --upgrade pip
   pip install -r requirements.txt

3. Configure environment variables:

cp .env.example .env
   nano .env

Update the values in `.env`:

4. Run the server:

python main.py

Daily Usage

After initial setup, to run the server:

cd plex-mcp-server
source venv/bin/activate  # Activate virtual environment
python main.py            # Start server
# When done: deactivate   # Exit virtual environment

Claude Desktop Configuration

Add to your Claude Desktop `config.json`:

{
  "globalShortcut": "",
  "mcpServers": {
    "plex": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://your-server:8000/sse",
        "--allow-http"
      ]
    }
  }
}

Available Tools

Movie Tools

• `get_library_stats` - Overall library statistics
• `list_all_movies` - Browse all movies with pagination
• `search_movies` - Search by title
• `search_by_genre` - Find movies by genre
• `search_by_director` - Find movies by director
• `search_by_year_range` - Find movies by year range
• `get_all_genres` - List all available genres
• `get_all_directors` - List all directors
• `get_recent_movies` - Recently added movies

Project Structure

plex_mcp_server/
├── main.py              # FastAPI server
├── config.py            # Configuration
├── plex_client.py       # Plex connection
├── mcp_handler.py       # MCP message handling
├── tools/
│   ├── movie_tools.py   # Movie-related tools
│   └── tv_tools.py      # TV tools (future)
└── requirements.txt     # Dependencies

Development

To add new tools:

1. Add methods to the appropriate tools file

2. Update the `get_tool_definitions()` method

3. Register the tool in `mcp_handler.py`

License

MIT License