Oraclarr

---

できること

Oraclarr を使うと、通常なら6つのウェブ UI を切り替えて調べる必要がある運用上の「なぜ」という質問に、言語モデルが一か所で答えられます。サービス全体から情報を集約し、何も変更せずに、構造化された単一の回答を返します。オプトインで使えるツール 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 が取得された、またはアップグレード中なのはなぜですか？（プロファイル、カスタムフォーマット、取得履歴）
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	1 つのシリーズまたは映画の更新、再スキャン、検索、名前変更、または Jellyfin のスキャンを開始します（オプトイン、2 段階）

インストール

実行方法は 2 つあります。どちらかを選んでください。

• 🐳 Docker（推奨）。 arr スタックの隣で常時稼働する小さなコンテナです。Dockge、Portainer、Unraid、および通常の docker compose で動作します。
• 🐍 Python（uv）。 コンテナを使わず、マシン上で直接実行します。ローカル開発や Docker を使わない場合に便利です。

どちらの方法でも、すべての設定は ORACLARR_ で始まる環境変数です。Docker の場合は、compose ファイルと同じ場所に .env ファイルを 1 つ用意します。Dockge と Portainer では、どちらもエディターに表示されます。.env.example を基にしてください。設定 にすべての変数が記載されています。.env がコミットされることはありません。

オプション A：Docker（推奨）

Oraclarr は長時間稼働するコンテナとして動作し、http://<host>:7979/mcp で HTTP 経由の MCP を提供します。同じフォルダーに docker-compose.yml と .env の 2 つのファイルが必要です。

スタックマネージャー（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 ソケットプロキシが追加されます。これは同じスタック内で稼働させる必要があるサイドカーです。コンテナ で説明しています。

次に、クライアントを接続してください。Claude Code にはコマンドを 1 つ、Claude Desktop、Cursor、Codex、VS Code、Gemini CLI、Windsurf には短い JSON ブロックを使用します。

オプション B：Python（uv）

Docker を使わずに Oraclarr を直接実行します。Python 3.12 以降と uv が必要です。

パッケージは PyPI で oraclarr-mcp として公開されています。MCP over stdio で通信するため、クライアントがプロセスを起動し、設定を 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"
  }
}

クローンから実行する場合（開発用）： 同じ ORACLARR_* の行をリポジトリフォルダー内の .env に記述します（起動時に読み込まれます）。その後、次を実行します。

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 ソケットプロキシと、そこを通過できるものについて説明します。
• 書き込み操作：2 つのスイッチ、トークン、2 段階の計画フロー、監査ログについて説明します。
• 設定ファイル：.env の代わりに（または併用して）config.yaml を使用する方法と、そこから移行する方法について説明します。
• アップグレード：特定のバージョンを超えてアップグレードする際に変更すべき内容について説明します。

ロードマップ

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 のスキャン）から開始しました。2 つのスイッチ、トークン、ドライランのプレビュー、監査ログによって制限されています。再試行とリクエスト承認は後日追加されます。
• 🔭 フェーズ 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 によって、何かがダウンロードされなかった理由を調べるために 6 つの Web UI を切り替える手間が省けたなら、コーヒーをごちそうしていただけると幸いです。