mcp-tautulli

Instructions

Implementation Reference

• tautulli.py:252-288 (handler)

  The tautulli_user_stats function is a tool that retrieves per-user watch statistics, including total plays, duration, and last seen activity from Tautulli. It uses the _api helper to fetch data.

  @mcp.tool()
  async def tautulli_user_stats(user: str = "", days: int = 30) -> str:
      """Get per-user watch statistics — total plays, watch time, last seen.
  
      Args:
          user: Filter to a specific username. If empty, shows all active users.
          days: Time range in days for stats (default 30).
      """
      days = _clamp_days(days)
      params: dict = {"length": "25", "order_column": "plays", "order_dir": "desc"}
      if user:
          params["search"] = _sanitize_str(user)
  
      data = await _api("get_users_table", **params)
      users = data.get("data", [])
  
      if not users:
          return "No users found."
  
      lines = ["User statistics:\n"]
      for u in users:
          name = u.get("friendly_name") or u.get("username", "?")
          plays = u.get("plays", 0)
          duration = _fmt_duration(u.get("duration", 0))
          last_played = u.get("last_played", "")
          last_seen = u.get("last_seen")
  
          if plays == 0:
              continue  # Skip inactive users
  
          parts = [f"  • {name}: {plays} plays, {duration} watched"]
          if last_played:
              parts.append(f"last: \"{last_played}\"")
  
          lines.append(" — ".join(parts))
  
      return "\n".join(lines)