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 Embymonitoring data: watch history, active streams, media, users, libraries, andrecently 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 inTracearr Settings > General — the key looks like trr_pub_<token>. Seethe API reference for details.
Install
Download a wheel from the latest releaseand 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 theserver still starts without one so errors surface from the API rather than atstartup.
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 asmovie:tmdb:584 or show:tvdb:81189. Cursor-paginated tools take cursorand page_size; read meta.nextCursor from the response and pass it back ascursor to fetch the next page. Optional params are omitted when unset so theAPI'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 toReleases whenever a v*tag is pushed - so the usual flow is make bump-patch, commit, then tag andpush.
The integration suite is read-only (the Tracearr public API has no writesurface), so it never modifies your instance.
