Initial commit: Plex MCP server with 6 tools and API passthrough
Some checks failed
Build and Push Docker Image / build (push) Failing after 0s
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.
This commit is contained in:
366
docs/api_reference.md
Normal file
366
docs/api_reference.md
Normal file
@@ -0,0 +1,366 @@
|
||||
# Plex API Quick Reference
|
||||
|
||||
This document provides a curated reference for the most commonly used Plex Media Server API endpoints. Use this with the `plex_api_call` tool for operations not covered by specific tools.
|
||||
|
||||
## Authentication
|
||||
|
||||
All requests require these headers (handled automatically by this MCP server):
|
||||
- `X-Plex-Token`: Authentication token
|
||||
- `X-Plex-Client-Identifier`: Unique client ID
|
||||
- `Accept: application/json`: Request JSON responses
|
||||
|
||||
## Pagination
|
||||
|
||||
Many endpoints support pagination via headers:
|
||||
- `X-Plex-Container-Start`: Starting offset (0-based)
|
||||
- `X-Plex-Container-Size`: Number of items to return
|
||||
|
||||
---
|
||||
|
||||
## Libraries
|
||||
|
||||
### List All Libraries
|
||||
```
|
||||
GET /library/sections/all
|
||||
```
|
||||
Returns all library sections (Movies, TV Shows, Music, etc.)
|
||||
|
||||
### Get Library Details
|
||||
```
|
||||
GET /library/sections/{sectionId}
|
||||
```
|
||||
Get details about a specific library section.
|
||||
|
||||
### List Library Contents
|
||||
```
|
||||
GET /library/sections/{sectionId}/all
|
||||
```
|
||||
List all items in a library. Supports filtering and sorting.
|
||||
|
||||
Query params:
|
||||
- `type`: Filter by type (1=movie, 2=show, 4=episode, 8=artist, 9=album, 10=track)
|
||||
- `sort`: Sort field (e.g., `titleSort`, `addedAt:desc`, `year`)
|
||||
- `X-Plex-Container-Start`: Pagination start
|
||||
- `X-Plex-Container-Size`: Page size
|
||||
|
||||
### Refresh Library (Scan)
|
||||
```
|
||||
POST /library/sections/{sectionId}/refresh
|
||||
```
|
||||
Trigger a library scan for new content.
|
||||
|
||||
Query params:
|
||||
- `force=1`: Force metadata refresh even if files unchanged
|
||||
- `path`: Restrict scan to specific path
|
||||
|
||||
### Cancel Library Refresh
|
||||
```
|
||||
DELETE /library/sections/{sectionId}/refresh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Metadata
|
||||
|
||||
### Get Item Metadata
|
||||
```
|
||||
GET /library/metadata/{ratingKey}
|
||||
```
|
||||
Get detailed metadata for a specific item.
|
||||
|
||||
### Get Children
|
||||
```
|
||||
GET /library/metadata/{ratingKey}/children
|
||||
```
|
||||
Get children of an item (e.g., seasons of a show, episodes of a season).
|
||||
|
||||
### Get All Leaves
|
||||
```
|
||||
GET /library/metadata/{ratingKey}/allLeaves
|
||||
```
|
||||
Get all leaf items (e.g., all episodes of a show).
|
||||
|
||||
### Refresh Item Metadata
|
||||
```
|
||||
POST /library/metadata/{ratingKey}/refresh
|
||||
```
|
||||
Refresh metadata for a specific item.
|
||||
|
||||
---
|
||||
|
||||
## Search
|
||||
|
||||
### Global Search
|
||||
```
|
||||
GET /hubs/search?query={searchTerm}
|
||||
```
|
||||
Search across all libraries.
|
||||
|
||||
Query params:
|
||||
- `query`: Search term (required)
|
||||
- `limit`: Max results per type
|
||||
- `sectionId`: Restrict to specific library
|
||||
|
||||
### Voice Search
|
||||
```
|
||||
GET /hubs/search/voice?query={searchTerm}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Hubs (Discovery)
|
||||
|
||||
### Get All Hubs
|
||||
```
|
||||
GET /hubs
|
||||
```
|
||||
Get discovery hubs (Continue Watching, Recently Added, etc.)
|
||||
|
||||
### Continue Watching
|
||||
```
|
||||
GET /hubs/continueWatching
|
||||
```
|
||||
|
||||
### Library Hubs
|
||||
```
|
||||
GET /hubs/sections/{sectionId}
|
||||
```
|
||||
Get hubs for a specific library.
|
||||
|
||||
---
|
||||
|
||||
## Playback Tracking
|
||||
|
||||
### Mark as Played (Scrobble)
|
||||
```
|
||||
GET /:scrobble?key={ratingKey}&identifier=com.plexapp.plugins.library
|
||||
```
|
||||
|
||||
### Mark as Unplayed
|
||||
```
|
||||
GET /:unscrobble?key={ratingKey}&identifier=com.plexapp.plugins.library
|
||||
```
|
||||
|
||||
### Update Timeline
|
||||
```
|
||||
GET /:timeline
|
||||
```
|
||||
Report playback progress.
|
||||
|
||||
Query params:
|
||||
- `ratingKey`: Item key
|
||||
- `key`: Full key path
|
||||
- `state`: playing, paused, stopped
|
||||
- `time`: Current position in ms
|
||||
- `duration`: Total duration in ms
|
||||
|
||||
---
|
||||
|
||||
## Ratings
|
||||
|
||||
### Rate an Item
|
||||
```
|
||||
PUT /:rate?key={ratingKey}&identifier=com.plexapp.plugins.library&rating={value}
|
||||
```
|
||||
Rating value: 0-10 (0 removes rating)
|
||||
|
||||
---
|
||||
|
||||
## Playlists
|
||||
|
||||
### List Playlists
|
||||
```
|
||||
GET /playlists
|
||||
```
|
||||
Query params:
|
||||
- `playlistType`: audio, video, photo
|
||||
- `smart`: 0 or 1
|
||||
|
||||
### Get Playlist
|
||||
```
|
||||
GET /playlists/{playlistId}
|
||||
```
|
||||
|
||||
### Get Playlist Items
|
||||
```
|
||||
GET /playlists/{playlistId}/items
|
||||
```
|
||||
|
||||
### Create Playlist
|
||||
```
|
||||
POST /playlists
|
||||
```
|
||||
Query params:
|
||||
- `title`: Playlist name
|
||||
- `type`: audio, video, photo
|
||||
- `smart`: 0 or 1
|
||||
- `uri`: Items to add (server://...)
|
||||
|
||||
### Add to Playlist
|
||||
```
|
||||
PUT /playlists/{playlistId}/items?uri={itemUri}
|
||||
```
|
||||
|
||||
### Delete Playlist
|
||||
```
|
||||
DELETE /playlists/{playlistId}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Collections
|
||||
|
||||
### List Collections
|
||||
```
|
||||
GET /library/sections/{sectionId}/collections
|
||||
```
|
||||
|
||||
### Get Collection Items
|
||||
```
|
||||
GET /library/collections/{collectionId}/items
|
||||
```
|
||||
|
||||
### Add to Collection
|
||||
```
|
||||
PUT /library/collections/{collectionId}/items?uri={itemUri}
|
||||
```
|
||||
|
||||
### Remove from Collection
|
||||
```
|
||||
DELETE /library/collections/{collectionId}/items/{itemId}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Play Queues
|
||||
|
||||
### Create Play Queue
|
||||
```
|
||||
POST /playQueues
|
||||
```
|
||||
Query params:
|
||||
- `uri`: Source URI
|
||||
- `type`: audio, video, photo
|
||||
- `shuffle`: 0 or 1
|
||||
- `repeat`: 0, 1, 2
|
||||
- `continuous`: 0 or 1
|
||||
|
||||
### Get Play Queue
|
||||
```
|
||||
GET /playQueues/{playQueueId}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Server Status
|
||||
|
||||
### Server Identity
|
||||
```
|
||||
GET /identity
|
||||
```
|
||||
Basic server info (machine identifier, version).
|
||||
|
||||
### Server Capabilities
|
||||
```
|
||||
GET /
|
||||
```
|
||||
Full server capabilities and features.
|
||||
|
||||
### Server Preferences
|
||||
```
|
||||
GET /:prefs
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Activities
|
||||
|
||||
### List Activities
|
||||
```
|
||||
GET /activities
|
||||
```
|
||||
Get running activities (transcoding, scanning, etc.)
|
||||
|
||||
### Cancel Activity
|
||||
```
|
||||
DELETE /activities/{activityId}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Butler (Scheduled Tasks)
|
||||
|
||||
### Get Butler Status
|
||||
```
|
||||
GET /butler
|
||||
```
|
||||
List scheduled maintenance tasks.
|
||||
|
||||
### Run Butler Task
|
||||
```
|
||||
POST /butler/{taskName}
|
||||
```
|
||||
Task names: BackupDatabase, BuildGracenoteCollections, CheckForUpdates, CleanOldBundles, CleanOldCacheFiles, DeepMediaAnalysis, GenerateAutoTags, GenerateChapterThumbs, GenerateMediaIndexFiles, OptimizeDatabase, RefreshLibraries, RefreshLocalMedia, RefreshPeriodicMetadata, UpgradeMediaAnalysis
|
||||
|
||||
### Stop Butler Task
|
||||
```
|
||||
DELETE /butler/{taskName}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Transcoding
|
||||
|
||||
### Get Transcode Sessions
|
||||
```
|
||||
GET /transcode/sessions
|
||||
```
|
||||
|
||||
### Stop Transcode Session
|
||||
```
|
||||
DELETE /transcode/sessions/{sessionKey}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Metadata Types Reference
|
||||
|
||||
| Type | Number | Description |
|
||||
|------|--------|-------------|
|
||||
| movie | 1 | Movies |
|
||||
| show | 2 | TV Shows |
|
||||
| season | 3 | Seasons |
|
||||
| episode | 4 | Episodes |
|
||||
| trailer | 5 | Trailers |
|
||||
| artist | 8 | Music Artists |
|
||||
| album | 9 | Music Albums |
|
||||
| track | 10 | Music Tracks |
|
||||
| photo | 13 | Photos |
|
||||
| photoalbum | 14 | Photo Albums |
|
||||
| playlist | 15 | Playlists |
|
||||
| collection | 18 | Collections |
|
||||
|
||||
---
|
||||
|
||||
## Common Query Parameters
|
||||
|
||||
Many list endpoints accept these query parameters:
|
||||
|
||||
- `type`: Filter by metadata type number
|
||||
- `sort`: Sort field with optional `:asc` or `:desc`
|
||||
- `X-Plex-Container-Start`: Pagination offset
|
||||
- `X-Plex-Container-Size`: Items per page
|
||||
- `includeChildren`: Include child items (1/0)
|
||||
- `includeElements`: Comma-separated list of elements to include
|
||||
- `excludeElements`: Comma-separated list of elements to exclude
|
||||
|
||||
---
|
||||
|
||||
## URI Format
|
||||
|
||||
When referencing items for playlists/queues:
|
||||
```
|
||||
server://{machineIdentifier}/com.plexapp.plugins.library/library/metadata/{ratingKey}
|
||||
```
|
||||
|
||||
Get machine identifier from `GET /identity`.
|
||||
Reference in New Issue
Block a user