tracearr-mcp

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, ported from the dashy-mcp template.

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.

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.