youtube-mcp

Read-only YouTube tools for eeyoren

A small MCP server that exposes four read-only tools over the YouTube Data API v3 and YouTube Analytics. Public channel and video stats run on an API key; analytics run on OAuth scoped to your own channel. Nothing here can upload, edit, delete, or comment.

Live MCP endpointhttps://<your-site>/mcp
01

Connect

Point any MCP client at the endpoint above. It speaks the MCP streamable HTTP transport over POST with JSON-RPC 2.0. Every request needs an Authorization: Bearer <token> header matching MCP_AUTH_TOKEN. Requests without a valid token are rejected with a 401.

{
  "mcpServers": {
    "youtube": {
      "url": "https://<your-site>/mcp",
      "headers": { "Authorization": "Bearer <your MCP_AUTH_TOKEN>" }
    }
  }
}

A raw request looks like this:

curl -s https://<your-site>/mcp \
  -H "Authorization: Bearer <your MCP_AUTH_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
02

Tools

All four tools are read-only. The first three use the Data API with your API key. The fourth, get_video_analytics, needs OAuth because Analytics data is only available to the authorized channel owner.

get_channel_stats

Data API

Channel metadata and statistics from the YouTube Data API v3. Pass a channelId or a forHandle like @eeyoren. Returns title, description, country, publish date, and subscriber, view, and video counts.

Arguments
{
  "channelId": "UC...",        // optional
  "forHandle": "@eeyoren"      // optional, either one
}
Example call
{ "name": "get_channel_stats", "arguments": {
  "channelId": "UCxxxxxxxxxxxxxxxxxxxxxx"
} }

get_video_stats

Data API

Metadata and statistics for one or more video IDs, up to 50 per call. Returns title, publish date, view, like, and comment counts, and duration.

Arguments
{
  "videoIds": ["videoId1", "videoId2"],
  "part": "snippet,statistics,contentDetails"  // optional
}
Example call
{ "name": "get_video_stats", "arguments": {
  "videoIds": ["dQw4w9WgXcQ"]
} }

list_recent_videos

Data API

A channel's recent public uploads from its uploads playlist. Supports maxResults (1 to 50, default 10) and pageToken for pagination.

Arguments
{
  "channelId": "UC...",
  "maxResults": 10,     // optional, 1-50
  "pageToken": "..."    // optional
}
Example call
{ "name": "list_recent_videos", "arguments": {
  "channelId": "UCxxxxxxxxxxxxxxxxxxxxxx",
  "maxResults": 5
} }

get_video_analytics

Analytics (OAuth)

Read-only YouTube Analytics metrics for a channel or video over a date range. Requires OAuth with the youtube.readonly and youtubeanalytics.readonly scopes and a refresh token; an API key alone is not enough.

Arguments
{
  "channelId": "UC...",   // optional, defaults to the authorized channel
  "videoId": "dQw4w9WgXcQ", // optional, restrict to one video
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "metrics": "views,estimatedMinutesWatched"  // optional
}
Example call
{ "name": "get_video_analytics", "arguments": {
  "startDate": "2024-01-01",
  "endDate": "2024-01-31"
} }
03

Environment variables

MCP_AUTH_TOKENRequired

Bearer token every MCP request must present. Compare with timing-safe logic; requests without it get a 401.

YOUTUBE_API_KEYRequired for Data API tools

Google Cloud API key. Powers get_channel_stats, get_video_stats, and list_recent_videos. Also passed to Analytics calls.

YOUTUBE_OAUTH_CLIENT_IDRequired for Analytics

OAuth 2.0 client ID for the refresh-token flow.

YOUTUBE_OAUTH_CLIENT_SECRETRequired for Analytics

OAuth 2.0 client secret for the refresh-token flow.

YOUTUBE_OAUTH_REFRESH_TOKENRequired for Analytics

Long-lived refresh token minted for your own channel. The server exchanges it for short-lived access tokens.

Set these in the platform's secure environment or secret configuration, never in source. A copy with placeholder names only ships in the repo as .env.example.

04

Setup

YouTube Data API key

  1. Go to the Google Cloud Console, create or pick a project, and enable the YouTube Data API v3.
  2. Under Credentials, create an API key and restrict it to the YouTube Data API v3.
  3. Set it as YOUTUBE_API_KEY in the platform's secret configuration.

OAuth for Analytics

  1. In the same project, enable the YouTube Analytics API and the YouTube Data API v3.
  2. Create an OAuth 2.0 client ID of type "Desktop" (or "Web" with your site as an authorized redirect URI).
  3. Use Google's OAuth 2.0 playground or a small script to authorize your own channel and mint a refresh token. Request only the read-only scopes: youtube.readonly and youtubeanalytics.readonly.
  4. Set YOUTUBE_OAUTH_CLIENT_ID, YOUTUBE_OAUTH_CLIENT_SECRET, and YOUTUBE_OAUTH_REFRESH_TOKEN in the platform's secret configuration.

The server uses the refresh-token flow: it exchanges the refresh token for a short-lived access token on each Analytics call (cached until it nears expiry). The refresh token is read only from server-side environment variables and is never returned to clients.

Bearer token

Generate a long random string and set it as MCP_AUTH_TOKEN. Every MCP request must send it in the Authorization header. Comparison is timing-safe, and the server refuses all requests when the token is not configured.

05

Security