# Plex MCP Server

A lightweight MCP (Model Context Protocol) server for interacting with Plex Media Server.

## Features

- **5 Specific Tools** for common operations:
  - `get_libraries` - List all library sections
  - `search_library` - Search for media by title
  - `get_metadata` - Get detailed item information
  - `get_recently_added` - Get recently added content
  - `refresh_library` - Trigger library scan for new content

- **API Pass-through** (`plex_api_call`) for accessing any of the 190+ Plex API endpoints

- **Documentation Resources**:
  - `plex://api-reference` - Curated API quick reference
  - `search_api_docs` - Search the full OpenAPI specification

## Quick Start

### Prerequisites

- Python 3.11+
- Plex Media Server with API access
- Plex authentication token ([how to find your token](https://support.plex.tv/articles/204059436-finding-an-authentication-token-x-plex-token/))

### Installation

```bash
# Clone the repository
cd plex-mcp-custom

# Install dependencies
pip install -e .

# Configure environment
cp .env.example .env
# Edit .env with your Plex URL and token
```

### Configuration

Edit `.env` with your Plex settings:

```env
PLEX_URL=http://your-plex-server:32400
PLEX_TOKEN=your-plex-token
PLEX_CLIENT_ID=plex-mcp-server
PORT=8000
```

### Running

```bash
# Direct
python server.py

# Or with uvicorn
uvicorn server:app --host 0.0.0.0 --port 8000
```

### Docker

```bash
# Build and run
docker-compose up -d

# Or build manually
docker build -t plex-mcp .
docker run -d --env-file .env -p 8000:8000 plex-mcp
```

## Usage

### MCP Client Configuration

Add to your MCP client configuration:

```json
{
  "mcpServers": {
    "plex": {
      "url": "http://localhost:8000/mcp/v1"
    }
  }
}
```

### Tool Examples

**List libraries:**
```
get_libraries()
```

**Search for a movie:**
```
search_library(query="Inception", limit=5)
```

**Get item details:**
```
get_metadata(rating_key="12345", include_children=true)
```

**Trigger library scan:**
```
refresh_library(section_id=1)
```

**Raw API call (mark as watched):**
```
plex_api_call(
  endpoint="/:scrobble",
  params='{"key": "12345", "identifier": "com.plexapp.plugins.library"}'
)
```

### Finding Endpoints

Use `search_api_docs` to find endpoints for specific operations:

```
search_api_docs(query="playlist")
search_api_docs(query="transcode")
search_api_docs(query="rating")
```

Or access the curated reference via the `plex://api-reference` resource.

## API Reference

See [docs/api_reference.md](docs/api_reference.md) for a curated guide to common endpoints.

The full OpenAPI specification is available in `openapi.json` and can be searched via the `search_api_docs` tool.

## Health Check

```bash
curl http://localhost:8000/health
```

Returns:
```json
{"status": "ok", "plex_connected": true}
```

## License

MIT