Plex MCP server

by rollecode

Overview Schema Source Related Servers Discussions Admin

Python

Remote

create_timeline

Idempotent

Report media playback state and position to Plex to keep timelines accurate and enable resume.

Instructions

Report media timeline.

POST /:/timeline

Args: key: The details key for the item. rating_key: The rating key attribute for the item. state: The current state of the media. play_queue_item_id: If playing media from a play queue, the play queue's ID. time: The current time offset of playback in ms. duration: The total duration of the item in ms. continuing: When state is stopped, a flag indicating whether or not the client is going to continue playing anothe item. updated: Used when a sync client comes online and is syncing media timelines, holds the time at which the playback state was last updated. offline: Also used by sync clients, used to indicate that a timeline is being synced from being offline, as opposed to being "live". time_to_first_frame: Time in seconds till first frame is displayed. Sent only on the first playing timeline request. time_stalled: Time in seconds spent buffering since last request. bandwidth: Bandwidth in kbps as estimated by the client. buffered_time: Amount of time in seconds buffered by client. Omit if computed by bufferedSize below. buffered_size: Size in kilobytes of data buffered by client. Omit if computed by bufferedTime above container_key: Groups timeline reports (e.g. /playQueues/123). guid: Global unique identifier for the item. play_queue_id: Identifies the play queue itself (distinct from playQueueItemID). url: Alternative to key/ratingKey (legacy).

Input Schema

TableJSON Schema

Name	Required	Description	Default
`key`	No
`url`	No
`guid`	No
`time`	No
`state`	No
`offline`	No
`updated`	No
`duration`	No
`bandwidth`	No
`continuing`	No
`rating_key`	No
`time_stalled`	No
`buffered_size`	No
`buffered_time`	No
`container_key`	No
`play_queue_id`	No
`play_queue_item_id`	No
`time_to_first_frame`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.0.0Sep 15, 2026

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint=false, destructiveHint=false, and idempotentHint=true, and the description does not contradict them. It adds useful field-level behavioral context such as sync-client semantics, 'Omit if computed by bufferedSize', and 'Sent only on the first playing timeline request', but it does not disclose overall side effects, required auth context, or typical frequency of calls.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured: a one-line purpose, the endpoint, then a parameter list where each entry earns its place by adding semantics not present in the schema. It is necessarily long due to 18 parameters, but a minor typo and the absence of a concise high-level 'what and when' sentence keep it from being excellent.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Parameter semantics are thoroughly covered and an output schema exists, so return-value expectations are presumably handled. However, with 0 required parameters, the description never states which fields are needed for a valid timeline report, when the call should be made, or how it relates to sibling playback control tools. That leaves meaningful ambiguity for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description is the only meaningful documentation for all 18 parameters. It provides units (ms, seconds, kbps), conditional relationships between fields, sync-client special cases, and legacy alternatives, going far beyond the sparse JSON schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Report media timeline' with the endpoint 'POST /:/timeline', and the parameter list makes clear this is a playback-timeline submission. It is identifiable as a distinct tool, though it does not explicitly contrast itself with sibling playback-control tools such as create_player_playback_set_state.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives. The description does not explain that this is the periodic client-to-server playback progress report, nor does it mention exclusions or relationships to the many sibling create_player_playback_* tools. The agent must infer usage from the parameter semantics.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server