yt-playlist-organizer-mcp

YouTube Data API v3を介してYouTubeプレイリストを整理するためのMCPサーバーです。

このサーバーが行うのはただひとつだけです。プレイリストとそのプレイリスト項目の作成・一覧表示・更新・削除です。動画、チャンネル、キャプション、コメント、登録チャンネル、その他のYouTube Data APIリソースには一切触れません。

公式の@modelcontextprotocol/sdkとYouTube Data API v3のRESTエンドポイントで構築されています（重いgoogleapis依存はありません）。

ツール

このサーバーが行うすべてです。他のツールはありません。

プレイリスト（/playlists）

プレイリスト項目（/playlistItems）

さらに、どの認証情報が設定されているかを確認するためのauth_statusがあります。

Related MCP server: youtube-mcp

設定

このサーバーが呼び出すのは/playlistsエンドポイントと/playlistItemsエンドポイントのみです。その他のYouTube Data APIは対象外です。

サーバーは2つの環境変数を読み取ります：

.env.exampleを参照してください。

• 読み取り（..._list）はAPIキー（またはアクセストークン）だけで動作します。

• 書き込み（insert/update/delete）とmine=trueは、スコープyoutube、youtube.force-ssl、またはyoutubepartnerを持つOAuth2アクセストークンが必要です。

OAuth2認証情報を取得する

1. Google Cloud Consoleでプロジェクトを作成します。

2. YouTube Data API v3を有効にします。

3. OAuth2クライアントID（デスクトップアプリ）を作成し、JSONをダウンロードします。

4. 認証情報をアクセストークンと交換します（例：Pythonのgoogle-auth-oauthlibやローカルのOAuthフローサービスを使用）。YOUTUBE_ACCESS_TOKEN=<token>を設定します。

5. （任意）読み取り専用でより簡単に使うには、APIキーを作成します。

Nix

NixOSに対応しています。flakeとshell.nixの両方を提供しています。

# Enter the dev shell (node + typescript toolchain)
nix develop

# or, non-flake:
nix-shell

ビルド

npm install        # install node deps (zod + MCP SDK)
npm run build      # emits dist/
npm run typecheck  # tsc --noEmit

ローカルで実行

# Reads only (API key):
YOUTUBE_API_KEY=... node dist/index.js

# Reads + writes/mine (OAuth access token):
YOUTUBE_ACCESS_TOKEN=... node dist/index.js

opencodeへの組み込み

mcpの下の~/.config/opencode/opencode.jsoncに以下を追加します：

"mcp": {
  "yt-playlist-organizer-mcp": {
    "type": "local",
    "command": ["node", "<path-to-repo>/dist/index.js"],
    "enabled": true,
    "environment": {
      "YOUTUBE_API_KEY": "{file:~/.secrets/yt-api-key}",
      "YOUTUBE_ACCESS_TOKEN": "{file:~/.secrets/yt-access-token}"
    }
  }
}

<path-to-repo>をクローンした絶対パスに置き換えるか、npmでインストールして名前で実行します：

npm install -g .
# then use:  "command": ["yt-playlist-organizer-mcp"]

代わりにNixシェル経由で実行するには、同じキーを使用してcommandを変更します：

"command": ["nix", "develop", "<path-to-repo>", "--command", "node", "dist/index.js"],

注意事項

• クォータコストは公式APIドキュメントに従い、ツールごとに記載しています。

• partの値は、各リソースの有効なセットに対して検証されます。

• playlists_list / playlistItems_listは、フィルターパラメータを正確に1つ必要とします。それ以外の場合は、入力検証で呼び出しが拒否されます。

• 更新ツール（playlists_update、playlistItems_update）は、最初に既存のリソースを読み取り、省略されたフィールド（例：description、privacyStatus、position、contentDetails）をクリアするのではなく保持します。したがって、更新のたびにクォータが追加で1回読み取りに消費されます。

• startAt/endAtは秒単位で指定し、APIに送信する前にISO 8601期間（PT1M30S）に変換されます。

開発

npm install
npm test         # vitest unit tests
npm run typecheck
npm run build

ライセンス

MIT