YouTube MCP

A local-first MCP server that lets AI assistants search YouTube, manage your channel and read your analytics, and asks you to approve every change first.

YouTube MCP is a Model Context Protocol server written in TypeScript. It exposes 74 tools to MCP clients such as Claude Code, Claude Desktop, Cursor and Codex. It runs on your own machine over stdio, keeps its OAuth tokens and working data on your disk, and never starts a network listener unless you ask for one.

Anything that changes your YouTube account goes through a preflight, approve, execute flow. The assistant first shows you exactly what it is about to do, and nothing happens until the exact previewed change is approved.

What it can do

Read (no account needed, just an API key)

• Search videos, look up videos and channels.
• List the public comments on a video.
• Fetch a public transcript (best effort; some videos have none).

Read (your own account and channel, via OAuth)

• Your channel, your subscriptions, and comment threads on your channel.
• Creator analytics: channel overview, top videos and audience retention for a date range.
• Your uploaded videos, playlists and playlist items, caption tracks, and the comment moderation queue.

Write (your own account, every change needs approval)

• Uploads: resumable video uploads, with status check, resume and cancel. Uploads are private unless you explicitly ask to publish.
• Videos: update title, description and other metadata, and set thumbnails.
• Captions: upload, update, download and delete caption tracks.
• Playlists: create, update, delete, and add, remove or reorder items. New playlists default to private.
• Comments and moderation: reply to comments, set a moderation status (including banning an author), and delete comments on your channel.
• Account actions: subscribe, unsubscribe, rate a video, post a top-level comment (these need a literal confirm: true).

Private viewing analysis (local only)

• Import your Google Takeout YouTube history and get a profile and trend comparison between two date ranges. The data stays in a local SQLite file.
• Save local curation allowlists and generate a finite, proposed queue. The server never applies a queue to your account.

Safety model

Write tools are built so an AI client cannot make a surprise change:

1. Preflight. A youtube_preflight_* tool reads fresh state from YouTube, validates the request and returns an exact preview.
2. Approve. A separate youtube_approve_* call, with confirm: true, binds approval to the profile, channel, target, requested change and fresh state. Approvals expire. They are stored locally, so an approved operation survives a server restart until it expires.
3. Execute. The write tool runs only with the same approved inputs and confirm: true.

More guard rails, all from the code:

• Mutations are never retried automatically. Ambiguous outcomes are reconciled with a read.
• Public visibility, scheduling, synthetic-media changes and banning an author need an explicit, elevated flag.
• Comment deletion requires the comment to belong to your selected channel.
• Caption downloads never overwrite an existing path or follow symbolic links.
• Creator tools check that the signed-in Google account matches the channel ID you configured.
• The automated tests never make a live mutation.

Full details are in docs/README.md.

Requirements

• Node.js 22 or newer
• A Google Cloud project with the YouTube Data API v3 enabled (and the YouTube Analytics API for the creator analytics tools)
• A YouTube Data API key for public reads, and an OAuth desktop client for account and creator tools

Setup

1. Install and build

git clone https://github.com/pratikgh0se/youtube-mcp.git
cd youtube-mcp
npm ci
npm run build

2. Create Google credentials

In the Google Cloud console:

1. Create or pick a project, then enable YouTube Data API v3 and YouTube Analytics API.
2. Create an API key. This is enough for the public tools.
3. For account and creator tools, configure the OAuth consent screen (add yourself as a test user while the app is in testing), then create an OAuth client ID of type Desktop app and download its JSON file.

3. Set environment variables

Copy .env.example to .env (it is git-ignored) or put these in your client config. Never commit real values.

4. Authorize once

npm run auth

This opens a browser for Google consent on a local 127.0.0.1 callback. It requests the youtube, youtube.force-ssl and yt-analytics.readonly scopes. Later calls refresh the token silently. Run it again if you revoke access.

Connect your MCP client

Use the absolute path to your checkout. The server is started with node and speaks stdio.

Claude Code

Add to .mcp.json in a project (or your user MCP config):

{
  "mcpServers": {
    "youtube-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/youtube-mcp/bin/youtube-mcp.mjs", "--transport", "stdio"],
      "env": {
        "YOUTUBE_API_KEY": "your-api-key",
        "YOUTUBE_OAUTH_CLIENT_SECRET_FILE": "/absolute/path/to/client_secret.json",
        "YOUTUBE_MCP_PROFILE_ID": "creator-main",
        "YOUTUBE_MCP_CHANNEL_ID": "UC..."
      }
    }
  }
}

Claude Desktop

Add the same mcpServers block to claude_desktop_config.json, then restart Claude Desktop.

Templates for Codex, Cursor, OpenClaw, Hermes, OpenCode and a generic stdio client are in configs/. They launch the youtube-mcp command, so they assume it is on your PATH. Otherwise change the command to node with the path above.

Optional: local HTTP

PORT=3000 node bin/youtube-mcp.mjs --transport http

This binds to 127.0.0.1 only. Do not expose it to the internet.

Example prompts

• "Search YouTube for recent talks about the Model Context Protocol and summarise the top three."
• "Get the transcript for this video and list the main points."
• "Show my channel's top 10 videos for the last 90 days and where viewers drop off in the most recent one."
• "Preview a private upload of /Users/me/videos/demo.mp4 titled 'Demo', and wait for me to approve it."
• "Create a private playlist called 'To review' and add these five videos to it. Show me the preview first."
• "List the unreplied comments on my latest video and draft replies for me to approve."
• "Import my Takeout watch history and compare what I watched in January with what I watched in June."

Tools

74 tools, grouped by area. Tools marked "preflight and approve" need the three-step flow above.

Privacy and security

• The OAuth refresh token is stored on your machine under ~/.youtube-mcp (or YOUTUBE_MCP_STATE_DIR), in a file with user-only permissions.
• Operation approvals, upload recovery state and your Takeout-derived SQLite database (consumption.sqlite) live in the same directory. The Takeout importer never sends data to YouTube.
• Your Google credentials go only to Google's APIs. The public transcript tool uses the youtube-transcript package to fetch captions from YouTube.
• The default transport is stdio. The optional HTTP transport binds to 127.0.0.1 only.
• Never commit .env, your OAuth client JSON, token state or Takeout exports. The .gitignore already excludes .env files.
• Running this server gives the AI client access to your YouTube account within the scopes you grant. Review each preview before approving it.
• To report a vulnerability, follow SECURITY.md and use GitHub's private reporting. Please do not open a public issue.

Development

npm ci
npm run lint            # type check the source
npm run typecheck:tests # type check the tests
npm test                # vitest, fully offline (202 tests)
npm run build           # compile to dist/
npm run smoke:read-only # offline by default; set YOUTUBE_LIVE_SMOKE=1 with an API key for one live read
npm run dev:stdio       # run from source over stdio

Continuous integration (.github/workflows/verify.yml) runs the same checks on Node 22. See docs/CHANGELOG.md for what has changed.

Contributing

Issues and pull requests are welcome. Please run npm run lint, npm run typecheck:tests and npm test before opening a pull request, add tests for any behavior change, and keep write actions behind the preflight and approve flow. Never include real credentials, tokens or personal data in issues, tests or fixtures.

License

MIT (c) 2026 Pratik Ghose