seerr-mcp-server

---

概要

Jellyseerr と Overseerr のメディアリクエストワークフローに対応します。TMDB に登録されたタイトルを検索し、正確な一致を確認して、利用状況とリクエスト状態をチェックしたうえで、Radarr/Sonarr が処理する保護機能付きリクエストを作成します。権限、割り当て上限、ルーティング、ステータスは Jellyseerr が管理します。このサーバーが Radarr/Sonarr を直接呼び出すことはありません。stdio プロセスまたはローカルの Streamable HTTP サーバーとして実行できます。

ツール

ツール	説明
seerr_search_media	タイトルから映画やテレビ番組を検索します。TMDB ID、公開年、概要、および Jellyseerr がすでに追跡しているタイトルのデコード済み利用状況を含む、順位付けされた一致候補を返します。リクエストの前に必ず実行する最初の手順です。
seerr_get_media	TMDB ID とメディアタイプを指定して、映画や番組の詳細を正確に取得し、書き込み前にタイトルを確認します。テレビ番組の場合は、シーズンごとの概要またはいずれか 1 シーズンのエピソード一覧を取得できます。
seerr_list_requests	ステータス、タイプ、リクエストユーザーで絞り込み、最近のリクエストを一覧表示します。適用したフィルターを返し、数値のステータスをすべてデコードします。タイトルは includeTitles で明示的に有効にした場合のみ含まれます。
seerr_request_media	保護機能付きの書き込みです。 デフォルトではリクエストのペイロードをプレビューします（mode: preview）。mode: request を指定し、確認が承認された場合に限り、リクエストを作成します。
seerr_request_status	ID でリクエストを 1 件取得します。タイトル、デコード済みリクエスト状態とメディア利用状況（4K を含む）、リクエストユーザー、ルーティングの概要、および状態に応じた次の手順のヒントを返します。
seerr_service_options	設定済みの Radarr/Sonarr サービス、デフォルトの品質プロファイル、インスタンスの機能フラグ（4K、部分リクエスト、スペシャル、メディアサーバー）の概要を表示します。ファイルシステムのパスは includePaths を指定しない限り伏せられます。

リソース

リソース	説明
seerr://request/{requestId}	1 件のリクエストの読み取り専用サマリーです。デコード済みのステータス、メディアの利用可能状況、リクエストしたユーザー、ルーティング情報を返します。seerr_request_status と同じ情報です。

すべてのリクエストデータはツールからも取得できます。リクエストの列挙には seerr_list_requests（ツールのみのアクセス方法）を使用します。

機能リファレンス

seerr_search_media _tool

• mediaType: movie | tv | all を指定してタイトルを検索します。人物は検索対象外です。page は 1～1000、limit は 1～20 で、デフォルトは 10 です。
• TMDB の検索結果と、追跡対象のタイトルについてデコード済みの status / status4k を返します。検索結果が空の場合は、ガイダンス通知とともに [] を返します。
• 任意の ISO 639-1 language を指定すると、ローカライズされたタイトルと概要が選択されます。

---

seerr_get_media _tool

• メディアの利用可能状況と、そのタイトルに対する既存の未完了リクエスト（重複リクエストを回避するため）を返します。
• TV の場合、シーズンごとのサマリーを取得するには seasonNumber を省略し、該当シーズンのエピソード一覧を取得するには指定します（シーズン 0 はスペシャルです）。
• 解決できない TMDB ID は、検索による再取得のヒントを含む型付きの media_not_found として返されます（Jellyseerr の生の HTTP 500 はサービスレイヤーで分類されます）。

---

seerr_list_requests _tool

• ライフサイクルの filter、mediaType、requestedById で絞り込み、added または modified を基準に昇順または降順で並べ替えます。take は 1～100 で、デフォルトは 20 です。skip はオフセットを指定します。
• デコード済みのステータス、リクエストしたユーザー { id, displayName }、適用したフィルターを示す補足情報を返します。
• includeTitles: true を指定すると、タイトルごとに一度だけメディアタイトルを結合します（デフォルトでは無効）。解決できない行もデータを保持し、通知でその旨を示します。

---

seerr_request_media _tool

• 書き込みは確認付きです。 mode: preview（デフォルト）では、解決されたタイトルと、書き込みを行わない正確な POST /request ペイロードを返します。mode: request では、同じ呼び出し元、タイトル、ペイロードに紐付けた確認を求めます。拒否、キャンセル、無効な回答の場合は request_cancelled を返します。
• TV のリクエストでは、seasons: "all" または [1, 2] のようなリストが必要です。シーズン 0（スペシャル）には、スペシャルエピソードの有効化が必要です。POST を行う前にインスタンスの機能チェックを実行します。既存のリクエストは出力に含まれ、重複リクエストが拒否された場合は duplicate_request を返します。
• 任意のルーティングの上書き項目：serverId、profileId、rootFolder、languageProfileId。省略すると、Jellyseerr のデフォルトが使用されます。

---

seerr_request_status _tool

• seerr_request_media の created.requestId または seerr_list_requests から取得した requestId を受け付けます。リクエストが見つからない場合は request_not_found を返します。
• デコード済みの requestStatus、mediaStatus / mediaStatus4k、リクエストしたユーザー { id, displayName }、ルーティング情報（serverId、profileName、is4k）、stateGuidance を返します。
• 呼び出しごとに title を結合します。tmdbId が存在しない場合、または検索に失敗した場合は含まれません。

---

seerr_service_options _tool

• インスタンスのバージョン、メディアサーバー、機能フラグ（movie4kEnabled、series4kEnabled、partialRequestsEnabled、specialEpisodesEnabled）、サービス ID、デフォルト、画質プロファイルを返します。
• サービスの一部で失敗した場合でも、利用可能な結果を保持し、通知を返します。
• includePaths: true を指定すると、ルートフォルダーのパスと空き容量を公開します。デフォルトではどちらも省略されます。

---

seerr://request/{requestId} _resource

• seerr_request_media または seerr_list_requests から取得した requestId を受け付けます。リクエストが見つからない場合は request_not_found を返します。
• マスキングとタイトルの結合を含め、seerr_request_status と同じ情報を返します。tmdbId が存在しない場合、または検索に失敗した場合は title は含まれません。リソースでは読み取りごとのオプションは指定できません。

機能

@cyanheads/mcp-ts-core を基盤としており、stdio および Streamable HTTP トランスポート、切り替え可能な認証（none / jwt / oauth）、切り替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレーシングを備えた構造化ログに対応しています。

HTTP では、2025 年頃の確認ラウンドにステートフルなセッションが必要です。MCP_SESSION_MODE=stateless を明示すると、起動に失敗します。同意記録の有効期限は 10 分で、記録が変更または再送された場合は、再度確認を求めます。引き換え処理では、同一プロセス内の同時リトライを排除します。リクエスト作成では POST を 1 回だけ試行し、自動リトライは行いません。インスタンス間の読み取りと削除はアトミックではありません。ルーティングされたリトライには、強整合性のある共有ファイルシステム、Supabase、または Cloudflare D1 ストレージを使用し、重複送信の競合にご注意ください。Cloudflare KV は同意記録には適していません。

Seerr 固有の機能：

• 読み取りとガード付きリクエストのみ対応 — 承認／却下、リトライ、編集／削除、メディア／ファイルの削除、ユーザー／設定／同期などの管理者スコープのエンドポイントは、API の制限ではなく、設計上対象外です
• PII／インフラ情報の秘匿化を 1 つの正規化処理に集約 — リクエスト元は { id, displayName } に変換され、オペレーターのメールアドレス、Plex／Jellyfin トークン、serviceUrl が出力に含まれることはありません。ファイルシステムのパスを含めるには includePaths を指定します
• ステータスのデコードを 1 つのヘルパーに集約 — リクエストとメディアのステータス（個別の 4K 利用可否を含む）は、どこでも { raw, label } にデコードされ、新しい Jellyseerr のステータスコードにも前方互換性があります
• キャッシュされたインスタンス設定に対する機能検証により、不正なリクエストの大半を API に送信する前に検出します
• 有効期間の短い設定キャッシュにより、プレビューのたびに往復通信する必要がありません

エージェントに適した出力：

• 出典情報と開示 — 検索結果には実際に使用したクエリが含まれ、上限に達したリストでは切り捨てが明示され、サービスの一部が縮退した場合にはデータを黙って除外せず、通知を表示します
• 型付きの実行可能なエラー — media_not_found、request_not_found、seasons_required、four_k_not_enabled、duplicate_request などのエラーには復旧のヒントが含まれており、呼び出し側は文章を解析せずに分岐してリトライできます

はじめに

次の設定を MCP クライアントの設定ファイルに追加し、SEERR_BASE_URL にご自身の Jellyseerr または Overseerr インスタンスを指定して、API キーを設定してください。

{
  "mcpServers": {
    "seerr-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/seerr-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "SEERR_BASE_URL": "http://localhost:5055",
        "SEERR_API_KEY": "your-api-key"
      }
    }
  }
}

または npx を使用する場合（Bun は不要です）：

{
  "mcpServers": {
    "seerr-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/seerr-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "SEERR_BASE_URL": "http://localhost:5055",
        "SEERR_API_KEY": "your-api-key"
      }
    }
  }
}

Streamable HTTP を使用するには、トランスポートを設定してサーバーを起動します。

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 SEERR_BASE_URL=http://localhost:5055 SEERR_API_KEY=your-api-key bun run start:http
# Server listens at http://localhost:3010/mcp

前提条件

• Bun v1.4.0 以降（または Node.js v24 以降）。
• Jellyseerr または Overseerr の実行中のインスタンスと、その API キー（Settings → General → API Key）。

インストール

1. リポジトリをクローンします：

git clone https://github.com/cyanheads/seerr-mcp-server.git

2. ディレクトリに移動します：

cd seerr-mcp-server

3. 依存関係をインストールします：

bun install

4. 環境を設定します：

cp .env.example .env
# edit .env — set SEERR_BASE_URL and SEERR_API_KEY

設定

設定はすべて、起動時に src/config/server-config.ts の Zod スキーマで検証されます。主な環境変数は次のとおりです。

変数	説明	デフォルト
SEERR_BASE_URL	必須。 Jellyseerr/Overseerr インスタンスのベース URL。例：http://localhost:5055。サービスが /api/v1 を追加するため、/api/v1 のサフィックスや末尾のスラッシュは不要です。	—
SEERR_API_KEY	必須。 Jellyseerr API キー（Settings → General → API Key）。X-Api-Key ヘッダーとして送信されます。	—
SEERR_REQUEST_TIMEOUT_MS	リクエストごとの HTTP タイムアウト（ミリ秒）。	15000
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_PORT	HTTP サーバーのポート。	3010
MCP_AUTH_MODE	認証モード：none、jwt、または oauth。	none
MCP_LOG_LEVEL	ログレベル（RFC 5424）。	info
LOGS_DIR	ログファイルのディレクトリ（Node.js のみ）。	<project-root>/logs
STORAGE_PROVIDER_TYPE	ストレージバックエンド。	in-memory
MCP_SESSION_MODE	HTTP セッションモード。確認ラウンドにはステートフルに解決される必要があります。サンプルと Docker イメージではステートフルに設定されています。値を設定しない場合は自動になり、ステートフルに解決されます。ステートレスを明示的に指定すると、起動に失敗します。	auto
MCP_REQUEST_STATE_KEY	同意記録 ID を保護する、任意のキー。32 バイト以上で、インスタンス間で共有される必要があります。	—
OTEL_ENABLED	OpenTelemetry の計装を有効にします。	false
OTEL_EXPORTER_OTLP_ENDPOINT	トレースとメトリクスの OTLP ベース URL。シグナル固有のエンドポイントがある場合は、そちらが優先されます。	—
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	オプトイン方式のログエクスポートエンドポイント。ベースエンドポイントを設定しても、ログは有効になりません。	—
LOG_TOOL_FAILURE_PAYLOADS	オプトイン方式で、失敗した呼び出しの引数／結果をログに記録します。キー名に基づいて秘匿化されるため、自由形式の値に含まれるシークレットは残る場合があります。	false

省略可能なオーバーライドの全一覧については、.env.example を参照してください。

サーバーの実行

ローカル開発

• ビルドして実行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• チェックとテストを実行：

  bun run devcheck   # Lint, format, typecheck, security, changelog sync
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t seerr-mcp-server .
docker run --rm \
  -e SEERR_BASE_URL=http://host.docker.internal:5055 \
  -e SEERR_API_KEY=your-api-key \
  -p 3010:3010 \
  seerr-mcp-server

Dockerfile のデフォルトは HTTP トランスポート、ステートフルセッションモードで、ログは /var/log/seerr-mcp-server に出力されます。OpenTelemetry のピア依存関係はデフォルトでインストールされます。これらを省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。

プロジェクト構成

ディレクトリ	目的
src/index.ts	createApp() のエントリーポイントです。6 つのツールと 1 つのリソースを登録し、Seerr サービスを初期化します。
src/config	サーバー固有の環境変数の解析と、Zod による検証を行います。
src/mcp-server/tools	ツール定義（*.tool.ts）。
src/mcp-server/resources	リソース定義（*.resource.ts）。
src/services/seerr	Jellyseerr API クライアント、ステータスデコーダー、PII／インフラの秘匿化ノーマライザー。
tests/	src/ の構成を反映した単体テストと統合テスト。

開発ガイド

開発ガイドラインとアーキテクチャ上のルールについては、CLAUDE.md/AGENTS.md を参照してください。要点は次のとおりです。

• ハンドラーは例外をスローし、フレームワークが処理します。ツールのロジック内で try/catch を使用しないでください。
• リクエストスコープのログ記録には ctx.log を、テナントスコープのストレージには ctx.state を使用します。
• 新しいツールとリソースは、src/mcp-server/*/definitions/index.ts のバレルを介して登録します。
• Jellyseerr API をラップする際は、まず生データを検証し、ドメイン型に正規化して秘匿化してから、出力スキーマを返します。不足しているフィールドを捏造せず、オペレーターの PII やパスを出力に含めないでください。

貢献

イシューを歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細は LICENSE を参照してください。