Metadata-Version: 2.4
Name: mcp-plex-server
Version: 0.1.3
Summary: MCP server for Plex media discovery, search, and library management
Keywords: mcp,plex,media,model-context-protocol
Author: Matthew O'Brien
Author-email: Matthew O'Brien <obrien.mlotwis@gmail.com>
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Video
Requires-Dist: mcp>=1.27.0,<2
Requires-Dist: plexapi>=4.16.0
Requires-Python: >=3.14
Project-URL: Repository, https://github.com/obrien-matthew/mcp-plex
Project-URL: Issues, https://github.com/obrien-matthew/mcp-plex/issues
Description-Content-Type: text/markdown

# mcp-plex

MCP server for Plex Media Server, focused on media discovery, search, and library management. 13 granular tools designed for use with Claude and other LLM agents.

## Prerequisites

- Python 3.14+
- [uv](https://docs.astral.sh/uv/)
- A running [Plex Media Server](https://www.plex.tv/)
- A Plex authentication token

## Setup

### 1. Get Your Plex Token

The easiest way to find your Plex token:

1. Sign in to [Plex Web App](https://app.plex.tv)
2. Browse to any media item and click **Get Info** (or **...** > **Get Info**)
3. Click **View XML** in the bottom-left
4. In the URL bar, find the `X-Plex-Token=` parameter -- that's your token

Alternatively, check the [Plex support article](https://support.plex.tv/articles/204059436-finding-an-authentication-token-x-plex-token/) for other methods.

### 2. Install

```bash
cd mcp-plex
uv sync
```

### 3. Configure Environment Variables

Set these before running the server:

```bash
export PLEX_SERVER_URL="http://your-plex-server:32400"
export PLEX_TOKEN="your_plex_token"
```

### 4. Test the Connection

```bash
uv run mcp-plex
```

The server connects to your Plex server on startup and verifies the token. If the connection fails, check that your server URL and token are correct.

## Claude Desktop / Claude Code Configuration

Add to your MCP server config. If installed from PyPI:

```json
{
  "mcpServers": {
    "plex": {
      "command": "uvx",
      "args": ["mcp-plex"],
      "env": {
        "PLEX_SERVER_URL": "http://your-plex-server:32400",
        "PLEX_TOKEN": "your_plex_token"
      }
    }
  }
}
```

Or if running from a local clone:

```json
{
  "mcpServers": {
    "plex": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-plex", "run", "mcp-plex"],
      "env": {
        "PLEX_SERVER_URL": "http://your-plex-server:32400",
        "PLEX_TOKEN": "your_plex_token"
      }
    }
  }
}
```

## Tools

### Discovery

| Tool | Parameters | Description |
|------|-----------|-------------|
| `search_media` | `query`, `media_type=""`, `limit=20` | Search across all libraries. Optional type filter: "movie", "show", "episode", "artist", "album", "track". |
| `get_recently_added` | `limit=20`, `library_name=""` | Recently added media, optionally filtered to a library. |
| `get_on_deck` | `limit=10` | Continue watching / next episode list. |

### Library Browsing

| Tool | Parameters | Description |
|------|-----------|-------------|
| `get_libraries` | (none) | List all library sections with types and item counts. |
| `get_library_contents` | `library_name`, `sort="titleSort"`, `limit=50` | Browse a library. Sort by title, date added, year, or rating. |
| `get_media_details` | `rating_key` | Full details for one item: summary, genres, cast, directors, ratings. |
| `get_library_stats` | `library_name=""` | Item counts and stats for one or all libraries. |

### Shows

| Tool | Parameters | Description |
|------|-----------|-------------|
| `get_seasons` | `rating_key` | List seasons for a TV show. |
| `get_episodes` | `rating_key`, `season_number=0` | List episodes (all or by season). |

### Collections & Playlists

| Tool | Parameters | Description |
|------|-----------|-------------|
| `get_collections` | `library_name` | List collections in a library. |
| `get_playlists` | (none) | List all playlists on the server. |
| `get_playlist_items` | `rating_key` | Get items in a playlist. |

### Management

| Tool | Parameters | Description |
|------|-----------|-------------|
| `scan_library` | `library_name` | Trigger a background library scan. |

## Development

```bash
uv run mcp-plex              # Run the server
uv run ruff check src/       # Lint
uv run ruff format src/      # Format
uv run pyright src/          # Type check
```

### Pre-commit Hooks

This project uses [lefthook](https://github.com/evilmartians/lefthook) for pre-commit checks. Install with `brew install lefthook` (or see [other install methods](https://github.com/evilmartians/lefthook/blob/master/docs/install.md)), then:

```bash
lefthook install
```
