Manual setup required. The maintainer's config contains paths only you know - edit the placeholders below before adding it to Claude Code.
1
Prepare the server locally
Run this once before adding it to Claude Code.
pip install mcp-tautulli2
Register it in Claude Code
claude mcp add -e "TAUTULLI_URL=${TAUTULLI_URL}" -e "TAUTULLI_API_KEY=${TAUTULLI_API_KEY}" mcp-tautulli -- python /path/to/tautulli.pyReplace any placeholder paths in the command with the real path on your machine.
Required:
TAUTULLI_URLTAUTULLI_API_KEY+ 1 optional3
Make your agent remember this setup
mcp-tautulli's config, env vars, and the gotchas you hit — recalled in every future Claude Code, Cursor, and Codex session.
npx conare@latestFree · one command · indexes the sessions already on disk. Set up in the browser instead →
What it does
- Provides 15 read-only tools for monitoring Plex via Tautulli
- Tracks streaming activity, playback history, and library statistics
- Supports advanced analytics like hourly viewing distribution and platform stats
- Simple configuration via environment variables
- Compatible with Claude Code and other MCP clients
Tools 15
tautulli_activityCurrent Plex streaming activity including who is watching, progress, and quality.tautulli_historyRecent playback history with filters for user, media type, search, and date.tautulli_recently_addedRecently added content in your Plex libraries.tautulli_searchSearch Plex content by title across all libraries.tautulli_user_statsPer-user watch statistics including plays, watch time, and last seen.tautulli_library_statsLibrary item counts, total plays, and last played per library.tautulli_most_watchedTop content by plays or duration for TV, movies, music, and users.tautulli_server_infoPlex server identity including name, version, platform, and connection.tautulli_statusServer configuration and reachability check.tautulli_transcode_statsDirect play versus transcode breakdown by platform.tautulli_platform_statsTop platforms and devices by plays and watch time.tautulli_stream_resolutionSource versus delivered resolution analysis.tautulli_plays_by_dateDaily play counts over time by stream type.tautulli_plays_by_day_of_weekWeekly viewing patterns showing which days see the most activity.tautulli_plays_by_hourHourly viewing distribution showing when people watch.Environment Variables
TAUTULLI_URLrequiredTautulli base URL (e.g. http://localhost:8181)TAUTULLI_API_KEYrequiredTautulli API key from Settings -> Web InterfaceTAUTULLI_TLS_VERIFYSet to false if using self-signed certsTry it
→Who is currently watching content on my Plex server and what are they watching?
→Show me the most watched movies in my library over the last month.
→What are the viewing patterns for this week? Which days are the busiest?
→Search for all content related to 'Breaking Bad' in my library.
→Give me a summary of my server's transcode statistics by platform.
Original README from lodordev/mcp-tautulli
mcp-tautulli
A single-file MCP server for Tautulli — Plex monitoring via Claude Code (or any MCP client).
15 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
pip install mcp-tautulli
Or from source:
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 (e.g. http://localhost: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:
{
"mcpServers": {
"tautulli": {
"command": "python",
"args": ["/path/to/tautulli.py"],
"env": {
"TAUTULLI_URL": "http://your-tautulli-host:8181",
"TAUTULLI_API_KEY": "your-api-key-here"
}
}
}
}
Or run standalone:
export TAUTULLI_URL="http://localhost:8181"
export TAUTULLI_API_KEY="your-api-key"
python tautulli.py
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) |
tautulli_recently_added |
Recently added content — what's new in your Plex libraries |
tautulli_search |
Search Plex content by title across all libraries |
tautulli_user_stats |
Per-user watch statistics — plays, watch time, last seen |
tautulli_library_stats |
Library item counts, total plays, last played per library |
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 |
All tools are read-only — this server does not modify any Tautulli or Plex state.
<details> <summary><strong>Example Output</strong></summary>tautulli_activity
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
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_search
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