Oraclarr

---

功能

Oraclarr 为大模型提供一个统一入口，用来回答日常运维中那些通常需要在六个网页界面间来回切换才能弄清楚的“为什么”问题。它汇总各项服务的信息，返回一份结构化的答案，不会更改任何内容。一个可选启用的工具 start_job 可以启动刷新、重新扫描、搜索或重命名。请参阅写入操作。

目前支持：Sonarr、Radarr、Sportarr、Prowlarr、qBittorrent、Tdarr、Profilarr、Jellyfin、Cleanuparr、Netdata、TrueNAS 和 Docker，也支持同一类型的多个实例（例如，单独用于动漫或 4K 内容的 Sonarr/Radarr）。每个工具都会遍历你定义的所有实例，并分别报告结果。

实际使用

连接后，直接提问即可。Oraclarr 会选择合适的工具并给出答案：

你问……	Oraclarr 运行	……并告诉你
“我的媒体栈里有服务宕机吗？”	stack_health	哪些服务无法访问、运行不健康或磁盘空间不足；如果某项服务宕机，还会报告其容器状态和退出代码
“为什么新一集 X 还没下载？”	diagnose	X 是否已在媒体库中、是否在下载队列中，或仍在待处理列表中
“为什么只允许英语配音时，却抓取了只有字幕的资源？”	explain_decision	被抓取的资源、自定义格式评分，以及匹配的语言格式
“为什么 Cleanuparr 即将移除此下载？”	get_queues + get_cleanup	该下载受到的违规记录及其类型、是否已标记为移除，以及适用的规则
“主机是否承受 I/O 压力？实际还剩多少 RAM？”	get_host	CPU 忙碌度和 I/O 等待、I/O 压力、空闲和可用内存、交换空间、ARC 使用量及其上限、GPU 温度和 VRAM
“Sonarr 今天记录了哪些错误？”	get_containers	容器日志中符合条件的日志行及其时间戳
“Sonarr 的重命名任务还在运行吗？”	get_jobs	正在运行和排队中的命令及其进度和涉及的剧集，还有任何失败的任务

工具

默认只读，且以结果为导向，而非每个端点对应一个工具，从而让模型保持准确。只有 start_job 会写入数据，并且仅在你启用写入功能时才会写入：

工具	解答的问题
stack_health	是否有服务宕机、不健康或磁盘空间不足？
get_queues	统一查看活动下载（arr 队列 ↔ qBittorrent）和停滞任务
diagnose	X 在处理流程的哪个环节 / 为什么还没到这里？
explain_decision	为什么抓取了 X 或正在升级 X？（配置档、自定义格式、抓取历史）
get_quality_config	质量配置档、自定义格式、发布配置档、Profilarr 同步状态
get_history	最近的抓取 / 导入 / 失败记录
get_wanted	缺少什么 / 未达到画质门槛？
search_media	我有 X 吗？它的状态是什么？
get_indexers	哪些索引器出现故障？
get_transcodes	有什么正在转码 / 卡住？
get_upcoming	接下来会播出或发布什么？它会入库吗？（最多 90 天）
get_library	Jellyfin 媒体库、扫描进度、任务、播放和转码、近期新增内容、名称搜索
get_cleanup	Cleanuparr 试运行状态、清理计划、做种和停滞规则、违规记录
get_host	主机 CPU/iowait、内存、交换空间、ARC、GPU、存储池、数据集、磁盘温度、TrueNAS 警报
get_containers	Docker 容器：状态、健康状况、重启次数、退出代码和筛选后的日志尾部
get_jobs	arr 和 Jellyfin 正在运行、排队、失败或计划执行的任务
start_job	在单个剧集或电影上启动刷新、重新扫描、搜索或重命名任务，或启动 Jellyfin 扫描（选择启用，分两步）

安装

有两种运行方式，任选其一：

• 🐳 Docker（推荐）。 在 arr 堆栈旁运行一个小型常驻容器。适用于 Dockge、Portainer、Unraid 和普通的 docker compose。
• 🐍 Python（uv）。 无需容器，直接在你的机器上运行。适合本地开发，或不使用 Docker 的情况。

无论使用哪种方式，每项设置都是以 ORACLARR_ 开头的环境变量。使用 Docker 时，只需在 compose 文件旁放置一个 .env 文件；Dockge 和 Portainer 的编辑器都会显示这两个文件。请从 .env.example 开始。配置列出了所有变量。你的 .env 文件绝不会被提交。

选项 A：Docker（推荐）

Oraclarr 以长时间运行的容器形式，通过 http://<host>:7979/mcp 提供 MCP HTTP 服务。你需要在同一个文件夹中放置两个文件：docker-compose.yml 和 .env。

使用堆栈管理器（Dockge、Portainer 等）： 创建一个新堆栈，将下面的 compose 内容粘贴到编辑器中，再将设置粘贴到堆栈的 .env 中。点击部署。Portainer 会将网页编辑器中的变量保存为 stack.env，因此在 Portainer 中请将 compose 配置行改为 env_file: stack.env。

使用命令行：

cp docker-compose.example.yml docker-compose.yml
cp .env.example .env    # then fill in your URLs and keys
docker compose up -d

这是完整的 compose 文件。添加或移除服务时无需编辑它；相关操作在 .env 中完成：

services:
  oraclarr:
    image: ghcr.io/bdog720/oraclarr-mcp:latest
    container_name: oraclarr
    restart: unless-stopped
    ports:
      - "7979:7979"           # left side is the host port; change it if 7979 is taken
    env_file: .env

也想查看容器状态和日志（get_containers）？请改用 docker-compose.full.example.yml。它会添加只读 Docker 套接字代理，这是唯一必须运行在同一堆栈中的 sidecar。容器中对此有说明。

然后连接客户端：为 Claude Code 执行一条命令，或为 Claude Desktop、Cursor、Codex、VS Code、Gemini CLI 或 Windsurf 添加一个小型 JSON 配置块。

选项 B：Python（uv）

无需 Docker，直接运行 Oraclarr。需要 Python 3.12+ 和 uv。

该软件包已发布到 PyPI，名称为 oraclarr-mcp。它通过 stdio 使用 MCP，因此客户端会启动进程，并在其 env 块中传入设置：

"oraclarr": {
  "command": "uvx",
  "args": ["oraclarr-mcp"],
  "env": {
    "ORACLARR_SONARR_URL": "http://192.168.1.10:8989",
    "ORACLARR_SONARR_API_KEY": "your-key",
    "ORACLARR_RADARR_URL": "http://192.168.1.10:7878",
    "ORACLARR_RADARR_API_KEY": "your-key"
  }
}

从克隆的仓库运行（用于开发）： 在仓库文件夹中的 .env 文件里加入相同的 ORACLARR_* 行（启动时会读取该文件），然后运行：

uv sync
uv run python -m oraclarr_mcp

在客户端配置中，使用 "command": "uv"、"args": ["run", "python", "-m", "oraclarr_mcp"]，并将 "cwd" 指向该仓库。

配置

每个服务都是一个 实例，名称由你选择。其设置是名为 ORACLARR_<NAME>_<FIELD> 的变量，只要设置了 _URL，实例就会存在：

ORACLARR_SONARR_URL=http://192.168.1.10:8989
ORACLARR_SONARR_API_KEY=your-key

ORACLARR_SONARR_ANIME_TYPE=sonarr           # a second Sonarr, named sonarr-anime
ORACLARR_SONARR_ANIME_URL=http://192.168.1.10:8990
ORACLARR_SONARR_ANIME_API_KEY=your-key

ORACLARR_QBITTORRENT_URL=http://192.168.1.10:8080
ORACLARR_QBITTORRENT_USERNAME=admin
ORACLARR_QBITTORRENT_PASSWORD=your-password

字段	适用于
_URL	每个实例
_TYPE	仅当名称不是服务类型时需要。类型：sonarr、radarr、sportarr、prowlarr、qbittorrent、tdarr、profilarr、jellyfin、cleanuparr、netdata、truenas、docker
_API_KEY	Sonarr、Radarr、Sportarr、Prowlarr、Profilarr、Jellyfin、Cleanuparr、TrueNAS
_USERNAME、_PASSWORD	qBittorrent
_ENABLED	可选；false 会关闭实例，但不会删除其配置行
_VERIFY_TLS	可选；false 表示接受自签名证书（TrueNAS）
_ALLOW_WRITES	可选；true 表示允许 start_job 对此实例执行操作。请参阅写入操作

名称中的下划线会转换为实例名称中的连字符，因此 SONARR_ANIME 会显示为 sonarr-anime。空白值会被视为未设置，因此可以保留未运行服务的配置行。拼写错误的 ORACLARR_ 变量会导致容器停止，并显示指出该变量的消息，而不是之后悄无声息地失败。

Jellyfin 需要 API 密钥（Dashboard → API Keys）。Cleanuparr 需要其账户 API 密钥（Settings → Account → API Key）。TrueNAS、Netdata 和 Docker 各自都有简短的设置指南，链接见下文。

服务端设置均为可选：

变量	默认值	功能
ORACLARR_TOOLSETS	media,downloads,transcode,library,host,containers	指定提供哪些工具组
ORACLARR_TOOL_BUDGET_SECONDS	30	每次工具调用的时限；响应较慢的实例会返回 status: "timeout"
ORACLARR_MAX_OUTPUT_BYTES	200000	防止响应过大的安全限制
ORACLARR_TIMEOUT_SECONDS	10	每次向服务发送请求的超时时间
ORACLARR_ALLOW_WRITES	false	启用 start_job。每个实例也必须设置自己的 _ALLOW_WRITES=true
ORACLARR_HTTP_TOKEN	未设置	至少 24 个字符。设置后，每个 HTTP 请求都需要 Authorization: Bearer <token>。通过 http 启用写入操作时必须设置此项

每次工具调用都有时间预算。如果实例未能及时响应，结果会包含 status: "timeout"，其他实例仍会返回数据。列表结果仅包含有用字段，并受每个工具的 limit 限制；若结果超出限制，truncated 和 total 会说明情况。响应和日志行中的 API 密钥及密码会显示为 ***。

指南

• 连接客户端：Claude Code、Claude Desktop、Cursor、Codex CLI、VS Code、Gemini CLI 和 Windsurf、令牌标头，以及为何不应使用云连接器。
• 主机指标：用于 get_host 的 TrueNAS 只读用户和 Netdata 容器。
• 容器：用于 get_containers 的 Docker socket 代理，以及它允许通过的内容。
• 写入操作：两个开关、令牌、两步计划流程和审计日志。
• 配置文件：使用 config.yaml 代替（或同时使用）.env，以及如何迁移离开它。
• 升级：跨越特定版本时需要更改的内容。

路线图

Oraclarr 分阶段构建。默认情况下为只读，写入功能则需要通过明确的安全门控才能启用。其架构（类型化客户端 + 结果工具 + 可通过配置选择的工具集）也旨在扩展到 *arr 以外的其他可自托管套件。

• ✅ 阶段 1：只读诊断。 Sonarr、Radarr、Sportarr、Prowlarr、qBittorrent、Tdarr、Profilarr、Jellyfin、Cleanuparr、TrueNAS、Netdata、Docker。
• 🔜 阶段 2：更多服务，仍为只读。 Seerr、Gluetun、Unpackerr、ntfy。该架构也可扩展到非 *arr 技术栈。
• 🚧 阶段 3：安全写入操作。 从 2.0.0 版开始，提供 start_job（刷新、重新扫描、搜索、重命名和 Jellyfin 扫描），并通过两个开关、令牌、试运行预览和审计日志进行门控。稍后会加入重试和请求审批。
• 🔭 阶段 4：破坏性操作。 删除媒体、加入阻止列表、技术栈控制和 Cleanuparr 更改，均需明确确认并通过允许列表限制。

想要支持某项服务？请提交 issue。

💬 反馈与问题

发现错误或有功能请求？请在 GitHub 上提交 issue。

🤝 参与贡献

欢迎提交 issue 和 PR。整个代码库均采用 TDD：

uv run pytest        # tests (respx-mocked, no live services needed)
uv run ruff check .  # lint

添加服务只需遵循一个简短流程（新建客户端 → 按 type 注册 → 扩展工具 → 编写测试）。请参阅 src/oraclarr_mcp/ 下的项目布局。

📄 许可证

Apache License 2.0。请参阅 LICENSE。

💖 支持项目

如果 Oraclarr 帮你省去了在六个 Web UI 之间切换、查找下载失败原因的麻烦，不妨请我喝杯咖啡。