mcp-tautulli

A single-file MCP server for Tautulli — Plex monitoring via Claude Code (or any MCP client).

19 read-only tools. No mutations. All configuration via environment variables.

Prerequisites

Python 3.10+
A running Tautulli instance with an API key
Claude Code (or any MCP-compatible client)

Installation

Terminal

pip install mcp-tautulli

Or install with uv:

bash

uv tool install mcp-tautulli

Or from source:

bash

git clone https://github.com/lodordev/mcp-tautulli.git
cd mcp-tautulli
pip install .

Configuration

Three environment variables:

Variable	Required	Default	Description
`TAUTULLI_URL`	Yes	—	Tautulli base URL with protocol (e.g. `http://localhost:8181` or `https://tautulli.example.com:8181`)
`TAUTULLI_API_KEY`	Yes	—	Tautulli API key (Settings → Web Interface → API Key)
`TAUTULLI_TLS_VERIFY`	No	`true`	Set to `false` if using self-signed certs (e.g. Tailscale serve)

Claude Code Setup

Add to your project's .mcp.json:

JSON Config

{
  "mcpServers": {
    "tautulli": {
      "command": "mcp-tautulli",
      "env": {
        // Include the protocol (http:// or https://)
        "TAUTULLI_URL": "http://your-tautulli-host:8181",
        "TAUTULLI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Desktop Setup

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

config.json

{
  "mcpServers": {
    "tautulli": {
      "command": "mcp-tautulli",
      "env": {
        "TAUTULLI_URL": "http://your-tautulli-host:8181",
        "TAUTULLI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Local Development Config

To point your MCP client at local source without reinstalling after every change, use uv run --directory instead of the installed binary:

config.json

{
  "mcpServers": {
    "tautulli-dev": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-tautulli", "mcp-tautulli"],
      "env": {
        "TAUTULLI_URL": "http://your-tautulli-host:8181",
        "TAUTULLI_API_KEY": "your-api-key-here"
      }
    }
  }
}

This works in both Claude Code (.mcp.json) and Claude Desktop (claude_desktop_config.json). Restart the client after code changes — no uv tool install needed.

Or run standalone:

server.ts

export TAUTULLI_URL="http://localhost:8181"
export TAUTULLI_API_KEY="your-api-key"
mcp-tautulli

Tools

Tool	Description
`tautulli_activity`	Current Plex streaming activity — who's watching what, progress, quality
`tautulli_history`	Recent playback history with filters (user, media type, search, date) — includes transcode decision; pass `include_ip=true` to show client IP (off by default, it's PII) and `include_performance=true` to also fetch per-record bitrate via `get_stream_data`
`tautulli_recently_added`	Recently added content — what's new in your Plex libraries
`tautulli_search`	Search Plex content by title across all libraries — output includes `[key: N]` rating keys
`tautulli_metadata`	Full metadata for one item by rating key — summary, cast/crew, genres, ratings, and media quality (resolution, codecs, HDR/Dolby Vision, file size). Server file paths omitted
`tautulli_item_stats`	Watch stats for one item — plays/time over 24h/7d/30d/all, plus which users watched it (friendly name only)
`tautulli_user_stats`	Per-user watch statistics — plays, watch time, last seen
`tautulli_library_stats`	Library item counts, total plays, last played per library — output includes `[id: N]` section ids
`tautulli_library_media_info`	Per-library media-quality breakdown — total size, item count, and per-item resolution/codec/container/size (find largest files)
`tautulli_most_watched`	Top content by plays or duration (TV, movies, music, users)
`tautulli_server_info`	Plex server identity — name, version, platform, connection
`tautulli_status`	Server config and reachability check
`tautulli_transcode_stats`	Direct play vs transcode breakdown by platform
`tautulli_platform_stats`	Top platforms/devices by plays and watch time
`tautulli_stream_resolution`	Source vs delivered resolution analysis
`tautulli_plays_by_date`	Daily play counts over time by stream type
`tautulli_plays_by_day_of_week`	Weekly viewing patterns — which days see the most activity
`tautulli_plays_by_hour`	Hourly viewing distribution — when people watch
`tautulli_stream_data`	Detailed stream performance data — bitrate, codec, transcode decision, bandwidth for a specific play (use `row_id` from history or `session_key` from activity)

All tools are read-only — this server does not modify any Tautulli or Plex state. Each tool calls a fixed Tautulli get_*/search command; there is no passthrough that could reach a write/destructive endpoint.

Privacy: user-identifying data is minimized by default — usernames, user IDs, emails, and thumbnails are never emitted (users appear by friendly name only), server file paths are omitted, and client IP addresses are opt-in (include_ip=true on tautulli_history). Note that Tautulli itself has no read-only API key — the key you configure is a full-access master key, so this server's read-only guarantee lives in its fixed command set, not in the credential.

Example Output

tautulli_activity

Code

2 active stream(s):

  • Alice playing "The Bear S02E06 — Fishes" — 45%, on Apple TV (direct play)
  • Bob playing "Oppenheimer (2023)" — 12%, on Roku (transcode)

Bandwidth: 18.5 Mbps total (LAN: 12.2, WAN: 6.3)

tautulli_plays_by_day_of_week

Code

Plays by day of week (last 30 days):

  Monday   :  91 ██████████████████████████████  (TV:62, Movies:18, Music:11)  ← peak
  Tuesday  :  76 █████████████████████████  (TV:56, Movies:15, Music:5)
  Wednesday:  62 ████████████████████  (TV:34, Movies:20, Music:8)
  Thursday :  45 ██████████████  (TV:32, Movies:8, Music:5)
  Friday   :  59 ███████████████████  (TV:37, Movies:14, Music:8)
  Saturday :  50 ████████████████  (TV:32, Movies:10, Music:8)
  Sunday   :  86 ████████████████████████████  (TV:60, Movies:16, Music:10)

Total: 469 plays, avg 67.0/day

tautulli_stream_data (pass row_id from history output)

Code

Stream Performance Data:

Media: Game of Thrones — The Red Woman (episode)

Quality Profile: Original
Source Bitrate: 10617 kbps
Source Video Bitrate: 10233 kbps
Source Audio Bitrate: 384 kbps

Stream Bitrate: 10617 kbps
Stream Resolution: 1080p
Stream Video Codec: h264
Stream Framerate: 24p
Stream Audio Codec: ac3
Stream Audio Channels: 6

Source Container: mkv
Source Video Codec: h264
Source Audio Codec: ac3
Source Resolution: 1080

Video Decision: direct play
Audio Decision: direct play

tautulli_metadata (pass [key: N] from search / recently-added)

Code

Example Movie (2019) — movie

Library: Movies
Content Rating: PG-13
Aired: 2019-05-01
Duration: 2h 10m
Ratings: audience 7.9
Genres: Adventure, Sci-Fi
Resolution: 1080p
Container: mkv
Video Codec: h264
Audio: eac3 6ch
File Size: 18.5 GB
Dynamic Range: SDR

IDs: imdb://tt0000000, tmdb://00000

tautulli_library_media_info (pass [id: N] from library stats)

Code

Library media info (section 1, 500 items, 4.2 TB total):

Resolutions (top 3): 1080:2, 4k:1

Items (sorted by file_size desc):
  • Example Feature (2021) — 4k, hevc, mkv, 42.0 GB
  • Another Movie (2018) — 1080, h264, mkv, 12.3 GB
  • A Third Film (2016) — 1080, h264, mp4, 9.8 GB

tautulli_search

Code

Search results for "breaking":

Movies:
  • Breaking (2012) — Movies

TV Shows:
  • Breaking Bad (2008) — TV Shows

Troubleshooting

"TAUTULLI_URL environment variable not set" Both TAUTULLI_URL and TAUTULLI_API_KEY must be set. Find your API key in Tautulli → Settings → Web Interface → API Key.

TLS/SSL errors If Tautulli is behind a reverse proxy with a self-signed certificate, set TAUTULLI_TLS_VERIFY=false.

"Tautulli unreachable" Verify the URL is accessible from the machine running the MCP server. Check firewalls and that Tautulli is running.

License

MIT