Ben
9931bdf2e4
Some checks failed
Build and Push Docker Image / build (push) Failing after 0s
- get_libraries: List all library sections - search_library: Search for media by title - get_metadata: Get detailed item info by rating key - get_recently_added: Get recently added content - refresh_library: Trigger library scan - plex_api_call: Raw API passthrough for any endpoint - search_api_docs: Search OpenAPI spec for endpoint documentation Includes Docker support and Gitea Actions workflow for container builds.
152 lines
2.8 KiB
Markdown
152 lines
2.8 KiB
Markdown
# 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
|