What can you do with this server?

mcp-tautulli is a read-only MCP server for monitoring and analyzing your Plex media server through Tautulli, offering 15 tools: * Live activity – See who's streaming, what they're watching, playback progress, quality, and bandwidth usage * Playback history – Retrieve recent watch history filtered by user, media type, title, or date * Recently added content – Browse newly added media across Plex libraries * Search content – Find media by title across all libraries * User statistics – Per-user play counts, total watch time, and last-seen info * Library statistics – Item counts, total plays, and last played content per library * Most watched content – Top TV shows, movies, music, or users ranked by plays or watch duration * Server info – Plex server name, version, platform, and connection details * Server status – Verify Tautulli configuration and reachability * Transcode analysis – Direct play vs transcode breakdowns by platform/device * Platform/device stats – Top streaming devices by plays and total watch time * Resolution analysis – Compare source quality vs delivered resolution * Daily play trends – Day-by-day play counts broken down by stream type * Weekly & hourly patterns – Identify peak viewing days and hours All operations are read-only. Configuration requires just a Tautulli URL and API key, and it works with Claude Code or any MCP-compatible client.

Which integrations are available for this server?

Provides tools for monitoring Plex media server activity, playback history, and statistics through Tautulli, including real-time stream status, library item counts, and per-user watch metrics.

mcp-tautulli

by lodordev

Overview Schema Source Related Servers Discussions Admin

Python

Remote

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)

Related MCP server: ntfy-mcp

Installation

pip install mcp-tautulli

Or install with uv:

uv tool 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 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:

{
  "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):

{
  "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:

{
  "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:

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.

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_stream_data (pass row_id from history output)

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)

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)

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

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

Available Tools

16 tools

tautulli_activityA

Get current Plex streaming activity — who's watching what, playback state, progress, and quality.

Use this before restarting Plex or rebooting servers to check for active streams.

Inputs: no named parameters. Returns: result

tautulli_historyB

Get recent Plex playback history.

Inputs: length, user, media_type, search, +3 more. Returns: result

tautulli_library_statsA

Get library-level statistics — item counts, total plays, and last played content per library.

Inputs: no named parameters. Returns: result

tautulli_most_watchedC

Get most watched content over a time period.

Inputs: days, stat_type, category. Returns: result

tautulli_platform_statsA

Get top platforms/devices by plays and total watch time.

Inputs: days. Returns: result

tautulli_plays_by_dateA

Get daily play counts over time, broken down by stream type (direct play, direct stream, transcode).

Inputs: days. Returns: result

tautulli_plays_by_day_of_weekB

Get weekly viewing patterns — which days of the week see the most Plex activity.

Inputs: days. Returns: result

tautulli_plays_by_hourB

Get hourly viewing distribution — when people watch Plex throughout the day.

Inputs: days. Returns: result

tautulli_recently_addedA

Get recently added content to Plex — shows what's new in your libraries.

Inputs: count, media_type. Returns: result

tautulli_searchB

Search Plex content by title — find movies, shows, episodes, and tracks.

Inputs: query (required), limit. Returns: result

tautulli_server_infoA

Get Plex server identity — name, version, platform, and connection details.

Inputs: no named parameters. Returns: result

tautulli_statusA

Check Tautulli server configuration and reachability.

Inputs: no named parameters. Returns: result

tautulli_stream_dataA

Get detailed stream performance data for diagnosing Plex playback issues.

Use row_id from history or session_key from current activity to fetch detailed performance metrics including bitrate, bandwidth, codec information, and connection details.

Inputs: row_id, session_key. Returns: result

tautulli_stream_resolutionB

Get source vs delivered resolution analysis — shows what quality your library serves and what clients actually receive.

Inputs: days. Returns: result

tautulli_transcode_statsA

Get direct play vs transcode breakdown by platform — shows which devices cause the most transcoding load.

Inputs: days. Returns: result

tautulli_user_statsA

Get per-user watch statistics — total plays, watch time, last seen.

Inputs: user, days. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.7/5.0

Scored 2026-06-23 17:15 across 16 tools

Disambiguation5/5

Each tool targets a distinct aspect of Plex monitoring: activity, history, various statistics, search, server info, etc. Descriptions clearly differentiate them, minimizing confusion.

Naming Consistency5/5

All tools follow a consistent 'tautulli_<descriptive_name>' pattern using lowercase with underscores. No mixing of conventions.

Tool Count5/5

With 16 tools, the set is well-scoped for a monitoring/stats server. It covers essential queries without being overwhelming.

Completeness5/5

The tool set covers a comprehensive range of monitoring needs: current activity, history, various statistics, search, server info, stream performance, and user stats. No obvious gaps for the stated domain.

Maintenance

ActivityInactive

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

mcpA
com.mux
The official MCP Server for the Mux API
Multimedia Processing Entertainment & Media API Testing
2168
https://mcp.mux.com
MatomoA
io.github.pipeworx-io
MCP server for matomo
Monitoring Data Visualization
481
https://gateway.pipeworx.io/matomo/mcp
smithery-ai-cookbook-python-quickstart
ai.smithery
A simple MCP server built with FastMCP and python
Developer Tools
213
https://server.smithery.ai/@smithery-ai/cookbook-python-quickstart/mcp
vulners-mcpA
io.github.vulnersCom
MCP server for the Vulners.com API
Security Penetration Testing Search
717
https://mcp.vulners.com/mcp

Related MCP Servers

mcp-server-prometheus
Monitoring Observability
loglmhq
A
license
Not graded
quality
D
maintenance
MCP server for interacting with Prometheus metrics and data.
Updated 2 years ago (2024-12-18 19:38 UTC)
17
MIT
ntfy-mcp
Communication
teddyzxcv
A
license
Not graded
quality
D
maintenance
The MCP server that keeps you informed by sending the notification on phone using ntfy.sh
Updated 2 years ago (2025-03-25 01:28 UTC)
284 npm
44
Apache 2.0
Plex MCP Server
Agent Orchestration Entertainment & Media
niavasha
A
license
B
quality
A
maintenance
A Model Context Protocol server that enables AI assistants to query and manage Plex Media Server content through natural language, providing library access, viewing statistics, and media management capabilities.
Updated 2 days ago (2026-11-10 13:44 UTC)
54
444 npm
57
JavaScript
MIT
prediction-market-mcp
Finance Search Open Data
JamesANZ
A
license
B
quality
C
maintenance
A simple MCP server that grabs prediction market data from polymarket, PredictIt, & Kalshi.
Updated a month ago (2026-10-15 22:49 UTC)
1
26 npm
38
MIT

mcp-tautulli

Prerequisites

Installation

Configuration

Claude Code Setup

Claude Desktop Setup

Local Development Config

Tools

Troubleshooting

License

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

mcp-server-prometheus

ntfy-mcp

Plex MCP Server

prediction-market-mcp