Skip to main content
Glama
Sign In
tracearr-mcp

tracearr-mcp

by arr-mcps
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

tracearr-mcp

Part of the arr-mcps collection. MCP server exposing Tracearr's Public API v2 (REST, read-only) as tools, so an LLM can query your Plex, Jellyfin, and Emby monitoring data: watch history, active streams, media, users, libraries, and recently added items.

Built with FastMCP.

Enabling the API on your Tracearr server

The Public API is read-only and requires a bearer API key. Generate one in Tracearr Settings > General — the key looks like trr_pub_<token>. See the API reference for details.

Related MCP server: Arr-MCP

Install

Download a wheel from the latest release and install it as a uv tool (no repo checkout needed):

uv tool install tracearr_mcp-*.whl

This puts a tracearr-mcp command on your PATH. Register it with Claude Code:

claude mcp add tracearr \
  --env TRACEARR_URL=https://your-tracearr-host \
  --env TRACEARR_API_KEY=<key> \
  -- tracearr-mcp

From source

uv sync
cp .env.example .env   # fill in TRACEARR_URL and TRACEARR_API_KEY
claude mcp add tracearr \
  --env TRACEARR_URL=https://your-tracearr-host \
  --env TRACEARR_API_KEY=<key> \
  -- uv run --directory /path/to/tracearr-mcp tracearr-mcp

Config

Env var

Required

Default

TRACEARR_URL

yes

-

TRACEARR_API_KEY

yes*

none (no auth header sent if unset)

* Every API endpoint requires auth; practically you must set it, but the server still starts without one so errors surface from the API rather than at startup.

Tools

One tool per Tracearr Public API v2 endpoint. All are read-only.

Tool

Endpoint

tracearr_get_history

GET /api/v2/public/history

tracearr_get_streams

GET /api/v2/public/streams

tracearr_get_media

GET /api/v2/public/media/{ref}

tracearr_get_media_children

GET /api/v2/public/media/{ref}/children

tracearr_get_media_stats

GET /api/v2/public/media/{ref}/stats

tracearr_get_media_watchers

GET /api/v2/public/media/{ref}/watchers

tracearr_get_media_history

GET /api/v2/public/media/{ref}/history

tracearr_list_users

GET /api/v2/public/users

tracearr_get_user

GET /api/v2/public/users/{id}

tracearr_get_user_stats

GET /api/v2/public/users/{id}/stats

tracearr_get_user_history

GET /api/v2/public/users/{id}/history

tracearr_list_recently_added

GET /api/v2/public/recently-added

tracearr_list_libraries

GET /api/v2/public/libraries

ref accepts a canonical media uuid or a type-qualified provider ref such as movie:tmdb:584 or show:tvdb:81189. Cursor-paginated tools take cursor and page_size; read meta.nextCursor from the response and pass it back as cursor to fetch the next page. Optional params are omitted when unset so the API's defaults apply.

Development

make help  # list all commands

Command

Does

make sync

uv sync

make test

Offline tests - one per endpoint, mocked HTTP

make test-integration

Tests against the live instance (needs TRACEARR_URL/TRACEARR_API_KEY)

make build

Build wheel + sdist into dist/

make bump-patch / bump-minor / bump-major

Bump the version in pyproject.toml + uv.lock

make clean

Remove build artifacts

The release workflow (.github/workflows/release.yml) builds and publishes to Releases whenever a v* tag is pushed - so the usual flow is make bump-patch, commit, then tag and push.

The integration suite is read-only (the Tracearr public API has no write surface), so it never modifies your instance.

Available Tools

13 tools
tracearr_get_historyA
Read-only

Cursor-paginated watch history, newest first, one record per play with canonical media identity on every record. A play is one resume chain.

Filters: user_id (Tracearr identity), server_id, media_id (canonical id; a show id matches all its episodes), rating_key (server-specific id), imdb_id/tmdb_id/tvdb_id, media_type (movie|episode|track|live|photo| unknown), watched (bool), since/until (date or ISO datetime). Pass meta.nextCursor back as cursor to fetch the next page.

Inputs: since, until, cursor, imdb_id, +9 more. Returns: object

tracearr_get_mediaA
Read-only

Resolve a media ref to its canonical identity, merged ids, and per-server availability. ref is a canonical media uuid or a type-qualified provider ref: {movie|show|episode}:{imdb|tmdb|tvdb}:{id} (e.g. movie:tmdb:584, show:tvdb:81189).

Inputs: ref (required). Returns: object

tracearr_get_media_childrenA
Read-only

List a show's seasons (with episode counts) or a season's episodes. ref is a canonical media uuid or a provider ref (seasons are uuid-only).

Inputs: ref (required). Returns: object

tracearr_get_media_historyA
Read-only

Cursor-paginated watch history for a single media item. ref is a canonical media uuid or a provider ref. Pass meta.nextCursor back as cursor.

Inputs: ref (required), cursor, page_size. Returns: object

tracearr_get_media_statsA
Read-only

Play counts, watch time, and distinct viewers for a media item across all_time, last_30, and last_7 windows, each with a combined and per-server breakdown. ref is a canonical media uuid or a provider ref.

Inputs: ref (required). Returns: object

tracearr_get_media_watchersA
Read-only

Per-account watchers of a media item, ordered by watch time. window is all_time|last_30|last_7 (default all_time). ref is a canonical media uuid or a provider ref.

Inputs: ref (required), window, server_id. Returns: object

tracearr_get_streamsA
Read-only

Currently active playback sessions across all servers. Each stream carries canonical media identity. Set summary=true to return only summary stats (omits the data array).

Inputs: summary, server_id. Returns: object

tracearr_get_userA
Read-only

Resolve a Tracearr identity id to its correlation block (linked accounts across servers).

Inputs: id (required). Returns: object

tracearr_get_user_historyA
Read-only

Cursor-paginated watch history for an identity, scoped to every account it owns. Pass meta.nextCursor back as cursor.

Inputs: id (required), cursor, page_size. Returns: object

tracearr_get_user_statsA
Read-only

Plays and watch time for an identity, summed across every account it owns, over all_time/last_30/last_7 windows, plus its top genres by play count.

Inputs: id (required). Returns: object

tracearr_list_librariesA
Read-only

Per-library rollups: item/movie/episode/show/track counts, total file size, and per-resolution counts for each server library.

Inputs: no named parameters. Returns: object

tracearr_list_recently_addedA
Read-only

Cursor-paginated library items ordered by server-reported added date, newest first. Filter by server_id, library_id, media_type (movie|episode| season|show|artist|album|track|photo). Set include_removed=true to include tombstones.

Inputs: cursor, page_size, server_id, library_id, +2 more. Returns: object

tracearr_list_usersA
Read-only

Cursor-paginated Tracearr identities, newest first, each with the media-server accounts it owns (account correlation is Tracearr-side). Set include_removed=true to include identities whose every account has been removed.

Inputs: cursor, page_size, include_removed. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4.1/5.0

    Scored across 13 tools

    Disambiguation3/5

    There are three history tools (get_user_history, get_history, get_media_history) that overlap because get_history can filter by user_id and media_id, subsuming the other two. Descriptions clarify the intended scope, but an agent may be unsure which to use for a specific query.

    Naming Consistency5/5

    All tool names follow the consistent pattern tracearr_<verb>_<noun> with verbs limited to get_ and list_. Naming is uniform, snake_case, and each noun clearly indicates the resource.

    Tool Count5/5

    13 tools is well-scoped for a media tracking server. Each tool covers a distinct aspect of the domain (history, streams, media metadata, users, libraries) without feeling bloated or sparse.

    Completeness4/5

    The tool surface covers core watch history, media resolution/stats, user identity, and library rollups. Minor gaps include no way to list available servers or search media by title, which could require working around with known IDs.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers

    • nas-mcp-server

      matthieurosset
      A
      license
      A
      quality
      C
      maintenance
      MCP server for managing a media server stack (Plex, Radarr, Overseerr, Bazarr, Prowlarr, Trakt.tv) using natural language to browse, request, and discover content.
      12
      MIT

    • Arr-MCP

      LtMarx
      A
      license
      A
      quality
      C
      maintenance
      MCP server to manage your *ARR media stack (Radarr, Sonarr, Lidarr, Readarr, Prowlarr) for searching, adding, and managing movies, TV shows, music, books, and indexers.
      1
      ISC

    • Oraclarr

      bdog720
      A
      license
      Not graded
      quality
      B
      maintenance
      A locally-run, read-only MCP server that lets an LLM client diagnose a self-hosted *arr media stack by aggregating across Sonarr, Radarr, Prowlarr, qBittorrent, Tdarr, and Profilarr.
      53 PyPI
      Apache 2.0
    • arr-mcp

      arr-mcp

      bardesss
      A
      license
      A
      quality
      A
      maintenance
      A unified MCP server for your self-hosted media stack (Radarr, Sonarr, Jellyfin, etc.). It correlates across services to answer questions no single service can, with safety features like untrusted-output fencing and safe-by-default deletions.
      2
      44
      140
      MIT

    Appeared in Searches