Plex MCPサーバー

Model Context Protocol (MCP) サーバーであり、AIアシスタントに対して、Plex Media Server、Sonarr、Radarr、およびTrakt.tvへの包括的なアクセスを単一の統合サーバーから提供します。

これは何ですか？

このMCPサーバーは、あなたのPlex Media ServerをAIでクエリ可能なデータベースに変えます。AIアシスタントに次のような質問をすることができます：

• 「最近見た映画は何？」

• 「先月の視聴統計を見せて」

• 「サーバーで最も人気のあるコンテンツは何？」

• 「ライブラリからアクション映画を探して」

• 「『視聴を継続』リストには何がある？」

• 「その新しい番組をSonarrに追加して」

• 「ダウンロードキューには何がある？」

• 「視聴履歴をTraktに同期して」

• 「まだ見ていない映画をいくつかおすすめして」

Related MCP server: YARR Media Stack MCP Server

機能

すぐに使える45個のツール（書き込み操作を有効にすると54個）：

• Plexライブラリ管理 — ライブラリの閲覧、メディアの検索、詳細なメタデータの取得、プレイリストとウォッチリストのリスト表示

• Tautulliスタイルの分析 — 視聴統計、ユーザーアクティビティ、人気コンテンツ、視聴履歴

• パーソナライズされたおすすめ — 視聴履歴、ジャンル、監督、俳優に基づいたAIによる映画の提案。マルチユーザーPlexサーバー向けのユーザー別プロファイルをサポート。

• Sonarr/Radarr統合 — シリーズ/映画の閲覧、検索、追加、キューの表示、ダウンロードのトリガー

• Trakt.tv同期 — OAuth認証、視聴履歴の同期、強化された統計、スクロブリング。設定すると、Traktデータがおすすめを充実させ、Plex以外で視聴した映画も補足します。

• 書き込み操作 (オプトイン) — プレイリストの作成/編集、メタデータの更新、ウォッチリストの管理

1つのサーバー、すべてのツール。 TraktおよびSonarr/Radarrの認証情報はオプションです。それらを必要とするツールは、キーが欠落している場合に役立つセットアップメッセージを返します。すべてを事前に設定する必要はありません。

クイックスタート

前提条件

• Node.js 20以上

• Plex Media Server (最近のバージョン)

• Plexトークン (Plexトークンの取得方法)

• MCP互換クライアント (Claude Desktopなど)

インストール

# Clone the repository
git clone https://github.com/niavasha/plex-mcp-server.git
cd plex-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

またはnpmから直接インストール：

npx plex-mcp-server

設定

1. Plexトークンを取得 (以下の手順を参照)

2. MCPクライアントを設定 (例: Claude Desktop):

{
  "mcpServers": {
    "plex": {
      "command": "node",
      "args": ["/path/to/plex-mcp-server/build/plex-mcp-server.js"],
      "env": {
        "PLEX_URL": "http://localhost:32400",
        "PLEX_TOKEN": "your_plex_token_here",

        "SONARR_URL": "http://localhost:8989",
        "SONARR_API_KEY": "optional_sonarr_api_key",

        "RADARR_URL": "http://localhost:7878",
        "RADARR_API_KEY": "optional_radarr_api_key",

        "TRAKT_CLIENT_ID": "optional_trakt_client_id",
        "TRAKT_CLIENT_SECRET": "optional_trakt_client_secret"
      }
    }
  }
}

PLEX_TOKENのみが必須です。 他のすべての認証情報はオプションです。設定されていないサービスのツールは、サーバーをクラッシュさせるのではなく、設定方法を説明する明確なエラーメッセージを返します。

Sonarr/Radarr APIキーは、各アプリのWeb UIの Settings > General > API Key にあります。

Trakt.tvのセットアップには、Trakt OAuthアプリケーションが必要です。リダイレクトURI urn:ietf:wg:oauth:2.0:oob で作成し、クライアントIDとシークレットを設定に追加してください。サーバーが実行されたら、AIアシスタントに「authenticate with Trakt」と伝えると、OAuthフローを案内してくれます。詳細な手順については、Traktセットアップガイドを参照してください。

v1.0.xには3つの個別のサーバーバイナリ (build/index.js, build/plex-trakt-server.js, build/plex-arr-server.js) がありました。v1.1.0以降では、これらは単一の統合バイナリ build/plex-mcp-server.js に置き換えられました。

古いバイナリは引き続き動作しますが、非推奨の警告が出力されます。MCP設定を build/plex-mcp-server.js を指すように更新し、重複するサーバーエントリを削除してください。

詳細については、移行ガイドを参照してください。

使用方法

設定が完了したら、AIアシスタントに次のように尋ねることができます：

"What movies did I watch last week?"
"Show me my most popular TV shows this month"
"Give me viewing statistics for the past 30 days"
"Search for Night of the Living Dead in my library"
"What's on my continue watching list?"
"List all my Plex libraries"
"Add that new show to Sonarr"
"What's in my Radarr download queue?"
"Sync my Plex history to Trakt"

推奨ワークフロー

Plexの視聴履歴をTraktに同期：

1. Traktの認証情報を設定する (上記参照)

2. 「Authenticate with Trakt」と尋ね、OAuthフローに従う

3. 「Do a dry run sync of my Plex history to Trakt」と尋ね、同期内容をプレビューする

4. 「Sync my Plex watch history to Trakt」と尋ね、実際の同期を実行する

新しいコンテンツを見つけて追加：

1. 「Search Sonarr for The Beverly Hillbillies」と尋ね、TVDB IDを見つける

2. 「Add The Beverly Hillbillies to Sonarr」と尋ねる（品質プロファイルとルートフォルダを自動検出します）

3. 「What's in my Sonarr download queue?」と尋ね、進捗を監視する

パーソナライズされたおすすめを取得：

1. 「Recommend me some movies from my library」と尋ねる

2. エンジンが視聴履歴（ジャンル、監督、俳優、評価）を分析します

3. 未視聴のすべての映画をスコアリングし、理由とともに上位の結果を返します

4. マルチユーザーサーバーの場合は、ユーザーを指定します：「Recommend movies for Titus」

5. Traktが設定されている場合、Traktの履歴も自動的に使用され、Plex以外で視聴した映画も考慮されます

クロスプラットフォームの視聴分析：

1. 「Show me my Plex viewing stats for the last 30 days」と尋ねる

2. 「What are my Trakt stats?」と尋ね、生涯統計（視聴した映画、時間、マイルストーン）を確認する

3. 「What are my most popular movies this month?」と尋ねる

利用可能な機能

Plexツール (19個)

書き込み操作 (9個、オプトイン)

PLEX_ENABLE_MUTATIVE_OPS=true を設定してこれらのツールを有効にします。これらはAIアシスタントがPlexサーバーに変更を加えることを許可します。注意して使用してください。これらのツールはテストされていますが、保証はありません。アシスタントが提案する変更を確認してから確定してください。

Sonarrツール (8個)

Radarrツール (8個)

クロスサービスツール (1個)

Traktツール (9個)

Plexトークンの取得方法

1. ブラウザで Plex Web App を開く

2. Settings > Account > Privacy に移動

3. 下部にある "Show Advanced" をクリック

4. Plex Token をコピー

別の方法:

• アクセス: http://YOUR_PLEX_IP:32400/web/index.html#!/settings/account

• 「Plex Token」フィールドを探す

プロジェクト構造

plex-mcp-server/
├── src/
│   ├── plex-mcp-server.ts    # Unified server entry point (44+ tools)
│   ├── index.ts               # Deprecated shim → plex-mcp-server
│   ├── plex-arr-server.ts     # Deprecated shim → plex-mcp-server
│   ├── plex-trakt-server.ts   # Deprecated shim → plex-mcp-server
│   ├── plex/                  # Shared Plex module
│   │   ├── client.ts          #   Plex API client
│   │   ├── tools.ts           #   Plex tool implementations
│   │   ├── tool-registry.ts   #   Map-based tool dispatch
│   │   ├── tool-schemas.ts    #   MCP tool schema definitions
│   │   ├── constants.ts       #   Configuration defaults
│   │   └── types.ts           #   TypeScript type definitions
│   ├── arr/                   # Sonarr/Radarr module
│   │   ├── client.ts          #   Base ArrClient + Sonarr/Radarr subclasses
│   │   ├── mcp-functions.ts   #   Tool implementations (17 tools)
│   │   ├── tool-registry.ts   #   Map-based tool dispatch
│   │   ├── tool-schemas.ts    #   MCP tool schema definitions
│   │   ├── constants.ts       #   Configuration defaults
│   │   └── types.ts           #   TypeScript type definitions
│   ├── trakt/                 # Trakt.tv module
│   │   ├── client.ts          #   Trakt API client + OAuth
│   │   ├── sync.ts            #   Plex-to-Trakt sync engine
│   │   ├── mapper.ts          #   Plex-to-Trakt data mapping
│   │   ├── mcp-functions.ts   #   Tool implementations (9 tools)
│   │   ├── tool-registry.ts   #   Map-based tool dispatch
│   │   └── tool-schemas.ts    #   MCP tool schema definitions
│   ├── shared/                # Shared utilities
│   │   └── utils.ts           #   truncate, sleep, chunkArray
│   └── __tests__/             # Test suite (94 tests)
├── build/                     # Compiled JavaScript output
├── docs/                      # Documentation
├── package.json
├── tsconfig.json
├── vitest.config.ts
├── .env.example               # Environment variables template
└── README.md

開発

スクリプト

# Development mode with auto-reload
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Run tests
npm test
npm run test:watch

ソースからのビルド

git clone https://github.com/niavasha/plex-mcp-server.git
cd plex-mcp-server
npm install
npm run dev

貢献

貢献を歓迎します！お気軽にプルリクエストを送信してください。大きな変更については、まずIssueを開いて議論してください。

開発ガイドライン

1. リポジトリをフォーク

2. 機能ブランチを作成 (git checkout -b feature/amazing-feature)

3. 変更をコミット (git commit -m 'Add amazing feature')

4. ブランチにプッシュ (git push origin feature/amazing-feature)

5. プルリクエストを開く

トラブルシューティング

よくある問題

接続拒否:

• Plexサーバーが実行されていることを確認

• 環境設定の PLEX_URL を確認

• ポート (通常32400) が正しいことを確認

認証エラー:

• Plexトークンが正しいことを確認

• Plex設定でトークンの権限を確認

• トークンの有効期限が切れていないことを確認

空の応答:

• 一部の機能にはPlex Passが必要です

• ライブラリにアクセスできるか確認

• メディアがスキャンされ、利用可能であることを確認

Sonarr/Radarr接続の問題:

• Sonarr/Radarrが実行されており、MCPサーバーホストからアクセス可能であることを確認

• APIキーが正しいことを確認 (Settings > General > API Key)

• Sonarrは /api/v3/ でAPI v3を使用します。URLに末尾のパスが含まれていないことを確認してください

• 大規模なRadarrライブラリ (2万本以上の映画) の場合、最初の radarr_get_movies 呼び出しに最大30秒かかる場合があります

Trakt認証の問題:

• TRAKT_CLIENT_ID と TRAKT_CLIENT_SECRET の両方が設定されていることを確認

• trakt_authenticate ツールを使用してOAuthフローを開始

• Traktからのコードを使用して trakt_complete_auth で認証を完了

MCPクライアントの問題:

• パスが build/plex-mcp-server.js (統合サーバー) に設定されていることを確認

• Node.jsがシステムPATHにあることを確認

• クライアント設定で環境変数が設定されていることを確認

ヘルプの取得

• Issueを開く

• 既存の ディスカッション を確認

• MCPドキュメント を確認

要件

• Node.js 20.0.0以上

• Plex Media Server (最近のバージョン)

• MCPサーバーとPlexサーバー間のネットワークアクセス

• 適切な