YouTube Channel Server

A Model Context Protocol (MCP) server that retrieves YouTube Channel statistics, metadata, and uploaded videos using the YouTube Data API v3.

This version is implemented in Python using FastAPI and the FastMCP SDK. It runs as an HTTP service over Server-Sent Events (SSE), making it ready for local development and cloud hosting on platforms like Vercel.

Features

• Server-Sent Events (SSE) Transport: Host your MCP server as a remote service.
• Auto-generated Docs: Swagger/OpenAPI interactive documentation automatically available at /docs.
• Flexible Queries: Search channel statistics and uploads using either a channel ID or handle (automatically handles @ prefix normalization).
• Vercel Ready: Contains a pre-configured vercel.json routing configuration.

---

Local Setup

1. Install dependencies:

   pip install -r requirements.txt
   

2. Add Environment Variables: Create a .env file in the project root:

   YOUTUBE_API_KEY=your_google_youtube_api_key_here
   

3. Run the Server: Start the FastAPI development server using Uvicorn:

   uvicorn api.index:app --reload
   

   The server will start at http://127.0.0.1:8000.

---

Interactive API Documentation

Once the server is running, you can access the interactive Swagger UI in your browser:

• Swagger Documentation: http://127.0.0.1:8000/docs
• Redoc Documentation: http://127.0.0.1:8000/redoc

You can test endpoints and check request/response schemas directly from the Swagger UI.

---

Connecting to Claude Desktop (SSE Mode)

To connect Claude Desktop to your locally running FastAPI server, edit your configuration file:

• Windows Path: %APPDATA%\Claude\claude_desktop_config.json
• macOS Path: ~/Library/Application Support/Claude/claude_desktop_config.json

Add the server to mcpServers using the url property:

{
  "mcpServers": {
    "youtube-channel-info-sse": {
      "url": "http://127.0.0.1:8000/sse"
    }
  }
}

Ensure your FastAPI server is running (uvicorn api.index:app) before restarting Claude Desktop.

---

Deploying to Vercel

Because this server uses the SSE transport over standard HTTP endpoints, you can deploy it directly to Vercel:

1. Push your repository to GitHub.
2. Go to Vercel and import your project.
3. In Settings -> Environment Variables, add your:
   • YOUTUBE_API_KEY = <your_api_key>
4. Deploy!

Vercel will build the serverless functions. Your live remote MCP URL will be: https://your-project.vercel.app/sse You can then share this URL or use it in any remote-compatible MCP client configuration!

---

Available Tools

1. get_channel_details

Retrieves YouTube channel metadata and statistics.

• Arguments:
  • channel_id (string, optional): Unique ID of the channel (e.g. UC_x5XG1OV2P6uZZ5FSM9Ttw).
  • handle (string, optional): Custom handle of the channel (e.g. @GoogleDevelopers or GoogleDevelopers).

2. get_channel_videos

Retrieves recently uploaded videos for a channel.

• Arguments:
  • channel_id (string, optional)
  • handle (string, optional)
  • limit (number, optional, default: 10, max: 50): Number of videos to retrieve.

3. get_video_analytics

Retrieves public statistics (views, likes, comments) and metadata (duration, definition). When OAuth2 is configured, it also fetches private Analytics API metrics (watch time, retention/average percentage, subscriber gains/losses, shares).

Note: thumbnail impressions and CTR are not available through the public YouTube Analytics API (they are YouTube Studio-only metrics), so they cannot be returned by this tool.

• Arguments:
  • video_ids (string, required): Comma-separated list of video IDs (e.g. bfvS1UeAkN0,qnl8-PBJNu4).

4. get_channel_video_analytics

Retrieves recent uploads for a channel fully enriched with public statistics and private Analytics API metrics (if OAuth2 is configured).

• Arguments:
  • channel_id (string, optional)
  • handle (string, optional)
  • limit (number, optional, default: 10, max: 50)

---

Private YouTube Analytics Setup (OAuth2)

To retrieve private video-level performance metrics (such as watch time, average view duration/percentage, and subscriber changes), you must obtain Google OAuth2 Client credentials and a refresh token.

1. Google Cloud Console Setup

1. Go to the Google Cloud Console.
2. Create a new project (or select an existing one).
3. Enable both the YouTube Analytics API and the YouTube Data API v3.
4. Configure the OAuth Consent Screen:
   • Choose External user type.
   • Enter standard details (AppName, Support Email).
   • Add your own email as a Test User (required while in testing status).
5. Create Credentials:
   • Go to Credentials -> Create Credentials -> OAuth Client ID.
   • Select Web application as application type.
   • Add http://localhost:8080/ under Authorized redirect URIs.
   • Copy the generated Client ID and Client Secret.

2. Generate the Refresh Token

You can easily generate your refresh token using the helper script included in the repository:

1. Run the helper script:

   python get_refresh_token.py
   

2. Enter your Client ID and Client Secret when prompted.
3. The script will automatically open your web browser to sign in to your Google Account.
4. Sign in with the account owning the YouTube channel and grant the permissions.
5. Return to your terminal to copy the generated Refresh Token.

3. Environment Variables

Add the generated credentials to your .env (or Vercel Environment Variables):

YOUTUBE_CLIENT_ID=your_client_id
YOUTUBE_CLIENT_SECRET=your_client_secret
YOUTUBE_REFRESH_TOKEN=your_refresh_token

Troubleshooting: analytics missing even though OAuth is set up

If the analytics field is missing from tool responses, the response now includes an analyticsNote field on each video explaining why. Common causes:

1. The MCP client's OAuth token is not a Google token. Some MCP clients (e.g. ChatGPT connectors) send their own Authorization: Bearer token with every request. The server tries that token first, but if the Analytics API rejects it, it automatically falls back to the YOUTUBE_REFRESH_TOKEN flow — so make sure the three environment variables above are set in your deployment (e.g. Vercel → Settings → Environment Variables), then redeploy.
2. The videos don't belong to your channel. The Analytics API only returns private metrics for videos owned by the channel that authorized the OAuth credentials (ids=channel==MINE). Querying other channels' videos returns public statistics only.
3. Missing scope. The refresh token must be generated with the yt-analytics.readonly scope — use get_refresh_token.py, which requests it, and sign in with the Google account that owns the channel.