youtube-mcp

Local YouTube MCP server for Codex. It turns public video, channel, and playlist URLs into structured context, bounded public-comment retrieval, timestamped caption research, and owned-playlist management.

The repository is public, but the server is intentionally local and single-user: bring your own Google Cloud credentials, authenticate your own YouTube channel, and keep credentials and tokens on your machine. It is not a hosted service or a multi-user connector.

Tools

• youtube_get_video

• youtube_get_comments

• youtube_get_comment_replies

• youtube_find_comments

• youtube_get_channel

• youtube_get_channel_videos

• youtube_search_videos

• youtube_search_channels

• youtube_search_playlists

• youtube_get_playlist_items

• youtube_find_playlist_items

• youtube_plan_playlist_cleanup

• youtube_apply_playlist_cleanup

• youtube_list_transcript_languages

• youtube_get_transcript

• youtube_search_transcript

• youtube_get_authenticated_channel

• youtube_list_owned_playlists

• youtube_get_owned_playlist_items

• youtube_create_playlist

• youtube_update_playlist

• youtube_add_playlist_video

• youtube_remove_playlist_item

• youtube_reorder_playlist_item

• youtube_clone_playlist

Public research tools remain read-only. Authenticated V2 tools manage only playlists owned by the locally authenticated channel; the server does not expose account-library reads, media downloads, ASR generation, or background processing.

Related MCP server: YouTube MCP

Requirements

• Node.js 22+

• pnpm

• A Google Cloud project with YouTube Data API v3 enabled

• A restricted YouTube Data API key for public read tools

• yt-dlp on PATH for transcript tools (or YT_DLP_PATH)

Authenticated playlist tools additionally require a Google OAuth desktop client. ChatGPT access through an OpenAI Secure MCP Tunnel is optional; it is not needed for local Codex use.

Authenticated playlist setup

In Google Cloud, enable YouTube Data API v3, create an OAuth Desktop app client, and configure the loopback redirect URI from YOUTUBE_REDIRECT_URI (by default http://127.0.0.1:8787/callback) as required by that client configuration. Configure its client ID and optional client secret in .env, then run the local PKCE flow once:

pnpm auth:login
pnpm auth:status

Tokens are saved outside the repository at ~/.config/youtube-mcp/tokens.json with private filesystem permissions. pnpm auth:logout revokes the local session when possible and removes that file.

youtube_list_owned_playlists and youtube_get_owned_playlist_items use explicit pagination. youtube_create_playlist defaults to private. Update and add operations apply directly; removal and reorder require confirm: true. Only playlists owned by the authenticated channel can be read through the owned workflow or changed.

Set YOUTUBE_SMOKE_OWNED_PLAYLIST_URL only for a private test playlist you own to add an authenticated, read-only ownership smoke check. It does not create, update, add, remove, or reorder items.

Setup

1. Copy .env.example to .env.

2. Set YOUTUBE_API_KEY to a restricted YouTube Data API key.

3. Install and build:

pnpm install
pnpm build

4. Run the stable local stdio server:

pnpm start

For contributor development only, run pnpm dev.

Codex setup

Build the server, then add a local MCP entry to your Codex configuration:

[mcp_servers.youtube]
command = "node"
args = ["--env-file=/absolute/path/to/youtube-mcp/.env", "/absolute/path/to/youtube-mcp/dist/server.js"]

Replace /absolute/path/to/youtube-mcp with your clone path. Rebuild after source changes before using the stable server.

Tool behavior

youtube_get_video accepts normal watch, Shorts, live, embed, and youtu.be URLs. It returns public metadata only.

youtube_get_comments accepts limit (default 50, maximum 100), order (relevance or time), an explicit pageToken, includeReplies, and optional matchTerms.

• A call fetches one page only and returns next_page_token when YouTube supplies one.

• includeReplies returns only the inline reply subset provided by YouTube. replies_truncated is true when more replies exist.

• matchTerms applies a case-insensitive literal OR filter after retrieving the page. When it is used, search_scope is always retrieved_page_only; it does not search every comment on the video.

youtube_find_comments searches a caller-specified maxPages (1–5) of comment threads for matchTerms. It returns searched_pages, complete, and next_page_token; its search_scope is always retrieved_pages_only.

youtube_get_channel accepts public /channel/CHANNEL_ID and /@handle URLs. youtube_get_channel_videos returns one explicit page of the channel's public uploads playlist.

youtube_search_videos returns one explicit page of public video search results, enriched with normalized video metadata. Search is quota-expensive, so requests are limited to 25 results.

youtube_search_channels and youtube_search_playlists provide the same bounded, enriched discovery flow for public channels and playlists. youtube_get_comment_replies retrieves one explicit reply page for a known parent comment.

youtube_get_playlist_items accepts public /playlist?list=... and /watch?...&list=... URLs and returns one explicit item page. Items retain their playlist item IDs and positions for safe future authenticated workflows.

youtube_find_playlist_items matches literal terms across at most five public or owned-playlist pages. youtube_plan_playlist_cleanup is owned-playlist-only and returns deterministic duplicate/unavailable-item removal recommendations; it never mutates and does not infer subjective sequencing. For a truncated cleanup pass, provide its opaque next_cursor to continue while retaining duplicate-detection context. youtube_apply_playlist_cleanup executes only caller-supplied exact planner removals and requires confirm: true; it checks every item before deleting, then reports a stopped partial result if YouTube rejects a later deletion.

youtube_clone_playlist requires confirm: true and copies at most five explicit source pages (250 items) from a public or owned source into a new owned playlist. It preserves source order and duplicate videos, reports unavailable source items instead of hiding them, and never rolls back a partially copied target. Every playlist write is read back and verified before success is returned.

youtube_add_playlist_videos appends a reviewed list of up to 250 public video URLs to an owned playlist in the supplied order. It requires confirm: true, validates every requested video before its first write, and stops with exact completed, remaining, and indeterminate IDs on a write failure.

youtube_apply_playlist_order applies a reviewed complete item-ID order to an owned playlist of at most 250 items. It requires confirm: true and rejects stale, incomplete, or duplicate item-ID lists before any mutation. Each move and the final full order are read back; a failure reports the observed order along with completed, remaining, and indeterminate IDs.

youtube_list_transcript_languages lists caption tracks exposed for a video. youtube_get_transcript returns one explicit page of timestamped creator or automatic caption segments. It prefers English when no language is requested, then falls back to the video language. Transcript retrieval uses local yt-dlp metadata and YouTube-exposed caption URLs; it never downloads media, writes a cache, or generates ASR text. A transient caption fetch is retried once with fresh metadata, but availability can change and is not guaranteed for every public video.

Caption discovery permits up to 32 MiB of yt-dlp output so videos with many automatic-caption languages can be inspected. Extraction failures return structured diagnostics with the discovery stage, video ID, backend version when available, process status, safe cause, and retryability. Known output-limit, timeout, authentication, rate-limit, blocked-request, and extractor failures are distinguished; diagnostic summaries are also logged to stderr without raw caption URLs or credentials.

youtube_search_transcript applies literal-term matching only to one explicit transcript segment window and returns matching timestamped segments with search_scope: "retrieved_segments_only". It accepts compatible cursors from either transcript tool.

If caption retrieval still returns HTTP 429 after the single fresh-URL retry, the tool reports youtube_rate_limited with retryable: false and guidance to stop transcript retrieval/search retries for that attempt. Try again later or use YouTube's Show transcript panel. A sanitized youtube_caption_fetch_failed stderr event records the video ID, status, and guidance without caption URLs or transcript text.

For an optional browser fallback, run pnpm exec playwright install chromium --no-shell and set YOUTUBE_BROWSER_TRANSCRIPT_FALLBACK=true in your local .env or server environment. After persistent caption-fetch HTTP 429, the server opens Show transcript in a temporary signed-out Chromium session. This fallback currently supports original English captions only. It verifies the browser caption inventory against the requested language and creator/automatic type, rejecting missing or ambiguous matches (including videos with both creator and automatic English tracks). It does not log in, reuse saved cookies, download media, or save transcripts. A browser read has a 45-second deadline after a bounded launch, and only one browser request runs at a time.

Fallback responses identify source: "browser" and durations_inferred: true; durations come from adjacent UI timestamps and the video's end time. Browser cursors keep subsequent retrieval/search on the browser path because its segment boundaries differ from caption tracks. Existing caption-track cursors are never silently switched to browser segments. Each page reopens the transcript without caching. YouTube verification prompts or changes to its page structure can still prevent retrieval.

The fallback reports transcript-panel HTTP rejections immediately instead of waiting for rows in an empty panel. browser_transcript_precondition_failed means YouTube returned HTTP 400 with FAILED_PRECONDITION; a manually opened signed-out browser may still succeed. This error does not establish that login is required or captions are missing. Diagnostics include only fixed lifecycle fields, video ID, status, and the recognized error code; they exclude cookies, verification tokens, signed URLs, upstream messages, and transcript text.

On macOS, an opt-in native Firefox backend uses actual pointer clicks instead of browser-protocol automation. Set YOUTUBE_BROWSER_TRANSCRIPT_BACKEND=firefox-native and YOUTUBE_NATIVE_FIREFOX_PROFILE to the absolute path of an existing dedicated profile, then rebuild. Open that profile in Firefox before requesting a transcript. The helper resolves the process holding that profile's lock; it never selects a default or everyday profile. Signing in is not required. macOS Accessibility access must be available to the MCP runtime; macOS builds also require Apple's Swift command-line tools.

The native backend briefly brings Firefox forward, reuses an existing tab already displaying the requested video, or creates one request window, then expands the description and clicks Show transcript. Before the first click, it moves the pointer within its window for eight seconds and waits another 28 seconds; this preparation runs once per request and stops if focus is lost. It may close and reopen an empty panel once, with a 60-second overall helper deadline. It reads all accessible rows in memory, verifies the requested video and the selected English / English (auto-generated) label, and infers durations as above. It closes only windows it created that still contain the original single tab showing the requested video. If tabs, navigation, or unreadable state make ownership uncertain, it leaves the window open. Existing windows are never closed. Four fresh-page trials on LfGenpmOjDQ retrieved 315 rows each with this preparation, whereas the matched delay-only trial failed. This is limited evidence from one video and session; the backend remains experimental and does not guarantee retrieval. Another app taking focus, an obscured target, or another Firefox window receiving focus stops the request. Only one native request may control the desktop at a time, including across MCP processes. Keep the desktop unlocked and the request window in front while it runs. No cookies or transcript files are exported, and it does not start playback. The Chromium backend and its temporary signed-out session remain the default on other installations.

Optional ChatGPT connection

For opt-in signed-in caption discovery, set YOUTUBE_COOKIES_BROWSER=chrome (or another browser listed in .env.example) in your private local environment, then rebuild and restart. You must also set YOUTUBE_COOKIES_PROFILE to an explicit dedicated profile directory to avoid selecting your everyday profile. yt-dlp reads that browser's local session without exporting a cookie file. macOS may request Keychain access for Chromium cookie decryption. Cookie values are never included in MCP results or diagnostics. This does not change playlist OAuth or the separate signed-out browser fallback.

Keep this server and .env on the Mac. Create an OpenAI Secure MCP Tunnel, run tunnel-client where it can reach the built stdio server, and register the tunnel endpoint in ChatGPT Developer Mode. The tunnel lets ChatGPT reach a private MCP server without a public listener; it is not a public plugin-distribution path.

For an optional persistent macOS setup, see the ChatGPT tunnel runbook. It uses a private runtime-key file and a user LaunchAgent so the tunnel starts again after login and stays available while the Mac is awake and online.

Tool handlers emit JSON timing entries to stderr: tool_start, tool_pending every 15 seconds while running, and tool_end with a success, error, or exception outcome. Entries contain a UTC timestamp, tool name, generated request ID, and elapsed milliseconds; they exclude arguments, response content, and exception details. In the persistent tunnel setup, these entries go to the configured error log. A start without an end identifies an unfinished handler; no start means the request has not reached a tool handler (including requests rejected before handler execution). Timing logs become active after rebuilding and restarting the server.

Do not commit the Google API key, OAuth client credentials, OpenAI runtime key, generated tunnel configuration, or local token file.

Privacy and API terms

This server runs locally. It does not include telemetry, a hosted backend, or a shared credential service. OAuth tokens are stored only in the local token file described above, and YouTube API requests use the credentials configured by the local user.

Users are responsible for their own Google Cloud projects and compliance with the YouTube API Services Terms of Service and YouTube Developer Policies. Caption tools use yt-dlp only to retrieve YouTube-exposed caption tracks; caption availability and extraction behavior can change without notice.

Verification

pnpm format:check
pnpm lint
pnpm typecheck
pnpm test
pnpm build
pnpm transcript:doctor
pnpm auth:status
pnpm smoke

pnpm smoke makes live read-only requests. It uses YOUTUBE_SMOKE_URL when set; otherwise it uses a default public video. Set YOUTUBE_SMOKE_COMMENTS_URL when you need to require a comments-enabled smoke target, and YOUTUBE_SMOKE_TRANSCRIPT_URL to verify a caption-enabled transcript target.