io.github.lanternrow/youtube-organic-mcp

youtube-organic-mcp

MCP server for YouTube organic analytics — channel stats, video performance, watch time, and audience engagement via the YouTube Data API v3 and YouTube Analytics API v2.

Built for Claude Code and any MCP-compatible AI tool. Gives your AI assistant direct, read-only access to your own channel's organic data — subscribers, views, watch time, per-video engagement, and day-by-day trends.

Part of The SEO Engine toolkit by Rex Jones — AI-powered SEO and social media tooling for agencies and businesses.

Why this exists

• No good open-source YouTube organic MCP existed. Plenty of ad MCPs; organic channel analytics, nobody.
• YouTube has the richest organic API of the major platforms. Watch time, average view duration, subscribers gained/lost, traffic sources — none of it gated behind a multi-week review.
• Reuses your existing Google OAuth. If you already run the GA4 / GSC / Google Ads MCPs, the same OAuth client works here.

Tools

Tool	Description
list_accounts	List configured channels and the default
get_channel_info	Channel profile + lifetime stats (subscribers, total views, video count, uploads playlist)
get_videos	Paginated uploads with per-video views, likes, comments, duration
get_video_details	Details for specific video IDs (batch up to 50)
get_channel_analytics	Channel analytics over a date range: views, watch time, avg view duration/%, subs gained/lost, likes, comments, shares — optionally by day
get_video_analytics	The same metrics for a single video over a date range

All tools accept an optional account parameter for multi-account setups.

Getting connected

Step 1: Enable the APIs

In Google Cloud Console (any project — you can reuse an existing one), enable YouTube Data API v3 and YouTube Analytics API.

Step 2: Get a refresh token

Create an OAuth client of type Desktop app and download its client_secret JSON. Then run the helper (needs pip install google-auth-oauthlib):

python3 scripts/get_youtube_token.py /path/to/client_secret.json my-channel

Authorize with the Google account that owns the channel (pick the Brand Account if prompted). It prints the three YOUTUBE_* values to drop into your config and writes them to .youtube_account.json (gitignored).

Step 3: Configure

Add to your Claude Code MCP settings:

{
  "mcpServers": {
    "youtube-organic": {
      "command": "node",
      "args": ["/path/to/youtube-organic-mcp/dist/index.js"],
      "env": {
        "YOUTUBE_CLIENT_ID": "your_client_id.apps.googleusercontent.com",
        "YOUTUBE_CLIENT_SECRET": "your_client_secret",
        "YOUTUBE_REFRESH_TOKEN": "1//your_refresh_token"
      }
    }
  }
}

Or set YOUTUBE_ACCOUNTS to a JSON array for multiple channels (see .env.example).

Architecture

src/
  index.ts          # MCP server entry point, tool registration
  accounts.ts       # Multi-account resolution (client_id/secret/refresh_token)
  client.ts         # OAuth token minting + Data/Analytics API HTTP client
  types.ts          # TypeScript interfaces for API responses
  tools/
    channel.ts      # get_channel_info + uploads-playlist resolver
    videos.ts       # get_videos, get_video_details
    analytics.ts    # get_channel_analytics, get_video_analytics

• Zero external HTTP dependencies — native fetch (Node 18+)
• Auto-refreshing auth — access tokens minted from the refresh token, cached per process
• Multi-account support — monitor multiple channels from one server

License

MIT