mcp-tautulli 是一个单文件 MCP 服务器，用于通过 Claude Code（或任何兼容 MCP 的客户端）访问 Tautulli，实现对 Plex 媒体服务器的监控。该服务器提供 19 个只读工具，不执行任何修改操作，所有配置均通过环境变量完成。
用途
该项目旨在让用户借助 MCP 客户端（如 Claude Code、Claude Desktop）查询 Tautulli 中记录的 Plex 监控数据，包括活动、历史、媒体库和用户统计、转码分析以及分辨率分布等。
主要能力
服务器包含 19 个只读工具，每个工具调用固定的 Tautulli get_* 或 search 命令，不存在可触及写入或破坏性端点的透传。资料中列出的工具包括： tautulli_activity tautulli_plays_by_day_of_week tautulli_stream_data（需传入历史输出中的 row_id） tautulli_metadata（需传入搜索/最近添加中的 [key: N]） tautulli_library_media_info（需传入媒体库统计中的 [id: N]） tautulli_search 其余工具名称资料中未逐一列出。
使用方式
前置条件：一个正在运行的 Tautulli 实例及其 API 密钥，以及 Claude Code（或任何兼容 MCP 的客户端）。 安装方式：资料提及可使用 uv 安装，或从源码安装（具体命令未在资料中给出）。 配置：需要设置三个环境变量，资料中明确提到 TAUTULLI_URL 和 TAUTULLI_API_KEY 必须设置，第三个环境变量名称未在资料中明确列出。API 密钥可在 Tautulli → Settings → Web Interface → API Key 中找到。 Claude Code 设置：将配置添加到项目的 .mcp.json 中。 Claude Desktop 设置：将配置添加到 macOS 的 ~/Library/Application Support/Claude/claude_desktop_config.json 或 Windows 的 %APPDATA%\Claude\claude_desktop_config.json 中。 本地开发配置：若希望 MCP 客户端指向本地源码而无需每次更改后重新安装，可使用 uv run --directory 代替已安装的二进制文件。此方式在 Claude Code（.mcp.json）和 Claude Desktop（claude_desktop_config.json）中均适用。代码更改后重启客户端即可，无需执行 uv tool install。也可独立运行。
隐私与安全
所有工具均为只读，服务器不会修改任何 Tautulli 或 Plex 状态。每个工具调用固定的 Tautulli get_* / search 命令，没有可到达写入/破坏性端点的透传。 隐私方面：默认最小化用户身份数据——用户名、用户 ID、电子邮件和缩略图从不输出（用户仅以友好名称显示），服务器文件路径被省略，客户端 IP 地址为可选（在 tautulli_history 上使用 include_ip=true）。需要注意的是，Tautulli 本身没有只读 API 密钥——所配置的密钥是完全访问的主密钥，因此该服务器的只读保证来自其固定命令集，而非凭据本身。
故障排除
“TAUTULLI_URL environment variable not set”：必须同时设置 TAUTULLI_URL 和 TAUTULLI_API_KEY。 TLS/SSL 错误：如果 Tautulli 位于使用自签名证书的反向代理之后，设置 TAUTULLI_TLS_VERIFY=false。 “Tautulli unreachable”：验证 URL 可从运行 MCP 服务器的机器访问，检查防火墙并确认 Tautulli 正在运行。
适用场景与限制
适用于需要通过 MCP 客户端查询 Plex 监控数据的用户，尤其是使用 Claude Code 或 Claude Desktop 的场景。限制包括：仅支持只读操作；需要自行准备 Tautulli 实例和 API 密钥；部分工具需要传入特定参数（如 row_id、[key: N]、[id: N]）；资料未提供完整的安装命令和第三个环境变量名称。
