tracearr-mcp-server

A minimal Model Context Protocol server that connects to Tracearr (who watches what on your Plex/Jellyfin/Emby servers: live streams, watch history, per-user and per-title stats), packaged for Docker. Every tool is read-only — Tracearr's Public API v2 has no write endpoints, so nothing here can change anything in Tracearr or on your media server.

It runs as a standing network service (streamable-http transport, not stdio), so any MCP client on your internal network can connect to http://<host>:<port>/mcp — the container isn't spawned per-client, and container lifecycle/updates can be handed off to a tool like Dockhand.

API assumptions

Built against Tracearr's Public API v2 (/api/v2/public, OpenAPI 3.0, version 2.0.0), which needs Tracearr 2.0.0 or later — earlier versions serve API v1 only and /ready will say so (HTTP 404). Auth is a Bearer API key (trr_pub_<token>) from Tracearr > Settings > General. The key must belong to an owner account, otherwise Tracearr answers 403.

There's no server-reported API version to negotiate (the /api/v2/public prefix is fixed), so there is no version environment variable. Tracearr rate-limits one budget per key across the whole v2 surface; a 429 is reported to the AI as exactly that, with a hint to wait.

Related MCP server: FoxTrove Voice MCP Server

Tools

A media ref is a canonical media UUID or a provider ref such as movie:tmdb:584 or show:tvdb:81189. Seasons have no provider ref: go show → media_children → season UUID → media_children. Paginated tools return meta.nextCursor; pass it back as cursor for the next page. Page sizes are clamped to what the API accepts (100, or 1000 for watched_media).

Privacy

This API returns people's viewing history, usernames and email addresses. Set MCP_AUTH_TOKEN (below) so only clients you've given the secret to can read it, and never expose the port outside your network. The server's own instructions tell the AI to share only what you asked for, but that is guidance to the AI, not a control — the token and the network boundary are the controls.

Health endpoints

Two plain HTTP endpoints, reachable without MCP_AUTH_TOKEN (so Docker's HEALTHCHECK, Dockhand, or any other monitor can poll them without the secret):

/ready says which of these it was: invalid or revoked key (401), key without an owner account (403), Tracearr too old to have the v2 API (404), rate limited (429), or unreachable.

Authentication

Set MCP_AUTH_TOKEN (a random shared secret — openssl rand -hex 32) and every request must carry Authorization: Bearer <token> or the server returns 401. This is checked by a small Starlette middleware in front of the MCP app, not the mcp SDK's built-in OAuth support (mcp.server.auth) — that machinery expects a full OAuth authorization server, which is unnecessary complexity for one secret shared by trusted LAN clients. This is a separate secret from TRACEARR_API_KEY — the latter authenticates this server to Tracearr, the former authenticates MCP clients to this server.

Leave MCP_AUTH_TOKEN unset and the server runs with no auth — anything that can reach http://<host>:<port>/mcp can read everything above. The server logs a warning on startup when it's running this way. Either way, the trust boundary is still the network:

• Do not publish this port through any reverse proxy, port-forward, or anything else reachable from outside your LAN/VLAN.

• Bind the compose ports: mapping to a specific internal interface (e.g. 192.168.1.50:8942:8942) if you want to be stricter.

Configuration

Environment variables (see .env.example):

Compose and $. Docker Compose interpolates $ in .env / .env.dockhand values, so a secret containing $ is silently truncated (abc$Xy1def becomes abc). Write $$ for a literal $, or single-quote the value. Generated trr_pub_... keys and openssl rand -hex tokens don't contain $.

Image

Built and pushed to ghcr.io/barrow1990/tracearr-mcp-server by .github/workflows/ci.yml, after the tests pass:

docker-compose.yml pulls :latest by default; swap in build: . there instead if you'd rather build locally from the Dockerfile. The image is a three-stage build that ends on a scratch base, the same shape as the other MCP servers in this stack.

Running with Docker Compose

cp .env.example .env   # fill in TRACEARR_URL / TRACEARR_API_KEY / MCP_AUTH_TOKEN
docker compose up -d --pull always

The server is then reachable at http://<docker-host>:8942/mcp from anything on your internal network.

Managing with Dockhand

Point Dockhand at ghcr.io/barrow1990/tracearr-mcp-server and let it track new tags. Make the GHCR package public, or every pull will need docker login ghcr.io with a PAT on each deploy host. Set a restart policy of unless-stopped (already in docker-compose.yml). The .env / .env.dockhand precedence works as in the other MCP-server repos.

Connecting a client

Claude Code

claude mcp add tracearr -s user --transport http http://<docker-host>:8942/mcp \
  --header "Authorization: Bearer <MCP_AUTH_TOKEN>"

(Drop the --header flag if you're running with MCP_AUTH_TOKEN unset.)

Claude Desktop

Claude Desktop's built-in config expects a locally-spawned command, so for a network server like this you'll need an HTTP-to-stdio bridge such as mcp-remote:

{
  "mcpServers": {
    "tracearr": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "http://<docker-host>:8942/mcp",
        "--header", "Authorization: Bearer <MCP_AUTH_TOKEN>"
      ]
    }
  }
}

Running without Docker

pip install -r requirements.txt
TRACEARR_URL=http://192.168.1.50:3000 TRACEARR_API_KEY=trr_pub_your_key \
MCP_AUTH_TOKEN=your-shared-secret python server.py

Testing

pip install -r requirements-dev.txt
python -m pytest tests/ -v

• tests/test_tools.py — every tool's request shape (path, parameters, dropped Nones, page-size clamping, safe path segments) and error mapping, against a mocked Tracearr (httpx.MockTransport, no extra mocking library needed).

• tests/test_http.py — /health, /ready, and the bearer-auth middleware, via server.build_app() (the exact app __main__ runs) through Starlette's TestClient.

• tests/test_live_tracearr.py — opt-in contract tests against a real Tracearr, to catch drift if an upgrade renames a field these tools rely on. Skipped by default; run with:

  RUN_LIVE_TRACEARR_TESTS=1 TRACEARR_URL=http://192.168.1.50:3000 \
  TRACEARR_API_KEY=<real trr_pub_... key> python -m pytest tests/test_live_tracearr.py -v

CI (.github/workflows/ci.yml) runs the mocked suite on every push/PR to main and dev; the GHCR build only runs after it passes.

Branch flow

main and dev are protected branches.

• dev is where changes land first. It can't be force-pushed or deleted. Every push to dev runs the tests and publishes ghcr.io/barrow1990/tracearr-mcp-server:dev (never :latest).

• main only changes through a pull request from dev. Direct pushes are blocked (for admins too), the test check must pass, and the source-branch check (enforce-dev-to-main.yml) fails any pull request into main that comes from another branch or from a fork. Merging is what publishes :latest.

• Merge dev into main with a merge commit, not squash or rebase: squashing rewrites dev's history, so dev and main diverge and every later pull request hits conflicts.

License

MIT