Skip to main content
Glama
YouTube Insights MCP

YouTube Insights MCP

by RaheesAhmed

YouTube Insights MCP

Ask Claude anything about any YouTube channel, including the private analytics of your own.

Python MCP FastMCP uv License: MIT

YouTube Insights MCP in Claude

YouTube Insights MCP is an open-source Model Context Protocol server. It connects Claude (or any MCP client) to the YouTube Data API v3 and the YouTube Analytics API. Instead of clicking through YouTube Studio, you just ask:

"Audit my channel and tell me why my Shorts stop at 1,200 views." "Compare my channel with @mkbhd and @veritasium." "Show the retention curve of my last Short. Where do people leave?" "Which of my videos brought the most subscribers this month?"


Contents


Related MCP server: youtube-mcp

Features

๐Ÿ”Ž Any public channel

Profile, every upload with tags and stats, comments, Shorts vs long-form detection, full performance report, side-by-side comparisons, view velocity, niche search

๐Ÿ“Š Your own channel

Engaged views, average % viewed, watch time, subscribers per video, retention curves, audience by country / age / gender / traffic source / device

โœ๏ธ Safe editing (opt-in)

Update titles, descriptions and tags. Every change is previewed and needs your approval

โšก Fast

HTTP/2 connection pooling, parallel batched requests and a local SQLite cache. Repeat questions answer in milliseconds and cost 0 quota

๐Ÿ” Secure by default

Bearer-token or Google OAuth 2.1 (PKCE) auth, email allowlist, read-only scopes, daily quota guard, no secrets in logs

๐ŸŒ Modern MCP

Streamable HTTP, stateless (spec 2026-07-28), so it runs locally or behind any load balancer


Quick start

What you need

  • uv (installs Python for you)

  • A Google account and a free Google Cloud project

Step 1: Get Google credentials

  1. In Google Cloud Console, create a project.

  2. APIs & Services โ†’ Library: enable YouTube Data API v3 and YouTube Analytics API.

  3. Credentials โ†’ Create credentials โ†’ API key. Copy the key.

  4. (Only for your own analytics) Credentials โ†’ Create credentials โ†’ OAuth client ID โ†’ Web application

    • Authorized redirect URI: http://localhost:8765/oauth2callback

    • Download the JSON and save it as secrets/google_client_secret.json

  5. (Only for your own analytics) OAuth consent screen / Audience

    • User type: External, status Testing

    • Test users โ†’ Add users: the Google account that owns your channel

Step 2: Install and configure

git clone https://github.com/RaheesAhmed/youtube-insights-mcp.git
cd youtube-insights-mcp
uv sync

Copy the example config:

cp .env.example .env          # macOS / Linux
copy .env.example .env        # Windows

Open .env and set at least:

YTMCP_YOUTUBE_API_KEY=your-api-key
YTMCP_BEARER_TOKENS=paste-output-of-gen-token
uv run youtube-insights-mcp gen-token     # creates a random access token
uv run youtube-insights-mcp doctor        # checks your setup

Step 3: (Optional) Sign in for your own analytics

uv run youtube-insights-mcp login --email you@gmail.com

Pick the account that owns the channel. If the channel is a brand account, pick the channel on the next screen. On a server with no browser, add --manual and paste back the address the browser lands on.

Step 4: Run

uv run youtube-insights-mcp serve
# โžœ http://127.0.0.1:8080/mcp

Connect to Claude

Claude Code

claude mcp add --transport http youtube-insights http://127.0.0.1:8080/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

Claude.ai / Claude Desktop (custom connector)

Custom connectors need a public HTTPS address and Google sign-in.

  1. Expose the server, for example with cloudflared tunnel --url http://localhost:8080, or deploy it.

  2. In .env:

    YTMCP_AUTH_MODE=google
    YTMCP_PUBLIC_BASE_URL=https://your-public-host
    YTMCP_JWT_SIGNING_KEY=output-of-gen-token
    YTMCP_ALLOWED_EMAILS=you@gmail.com
  3. Add https://your-public-host/auth/callback to the OAuth client's redirect URIs.

  4. In Claude: Settings โ†’ Connectors โ†’ Add custom connector, enter https://your-public-host/mcp, then Connect.

Each person signs in with their own Google account, so "my analytics" always means their channel.

Other MCP clients

Any client that supports Streamable HTTP works. Point it at http://127.0.0.1:8080/mcp and send Authorization: Bearer <token>.


Tools

Any channel (API key only)

Tool

What it does

Quota

get_channel_overview

Subscribers, views, video count, description, keywords, topics

1โ€“2

list_channel_videos

Every upload with title, tags, stats, duration and Short flag

~1 / 25 videos

get_video_details

Full metadata for up to 50 videos

1

get_video_comments

Top comments with likes and replies

1

analyze_channel

Shorts vs long, upload cadence, best hour/weekday, winning title words, top tags, outliers

~1 / 25 videos

compare_channels

2โ€“6 channels side by side

per channel

get_view_velocity

Views per hour since the last check

~1 / 25 videos

search_youtube

Find videos or channels in a niche

100

get_quota_status

Quota used today and remaining

0

Your channel (needs login or Google mode)

Tool

What it does

get_my_channel

Your channel profile and totals

get_my_video_performance

Per video: views, engaged views, avg % viewed, watch time, likes, shares, subscribers

get_my_audience

By country, age & gender, traffic source, device, subscribed status, content type or day

get_my_retention_curve

100-point retention curve, the steepest drop, and comparison with similar videos

query_my_analytics

Any YouTube Analytics metrics, dimensions and filters

record_studio_metrics / get_studio_metrics

Save numbers only Studio shows (Shorts viewed vs swiped, impressions, CTR)

update_video_metadata

Edit title, description or tags with preview + confirm (only when YTMCP_ENABLE_WRITE_TOOLS=true)

Good to know: no Google API gives the Shorts viewed vs swiped away percentage directly. engagedViews รท views from get_my_video_performance is a close stand-in.


Configuration

All settings live in .env. See .env.example for the full list.

Variable

Default

Description

YTMCP_YOUTUBE_API_KEY

required

Google Cloud API key

YTMCP_GOOGLE_CLIENT_SECRETS_FILE

./secrets/google_client_secret.json

OAuth client JSON (for your analytics)

YTMCP_AUTH_MODE

token

token, google or none (localhost only)

YTMCP_BEARER_TOKENS

Comma-separated tokens, 32+ characters each

YTMCP_PUBLIC_BASE_URL

Public https:// URL (google mode)

YTMCP_JWT_SIGNING_KEY

Random 32+ characters (google mode)

YTMCP_ALLOWED_EMAILS

anyone

Google accounts allowed in (google mode)

YTMCP_HOST / YTMCP_PORT

127.0.0.1 / 8080

Listen address

YTMCP_DATA_DIR

./data

SQLite cache and sign-in token

YTMCP_DAILY_QUOTA_UNITS

10000

Max Data API units per day

YTMCP_CACHE_TTL_SECONDS

3600

How long API responses are reused

YTMCP_ENABLE_WRITE_TOOLS

false

Allow editing your videos (run login again after enabling)

Commands

Command

Purpose

uv run youtube-insights-mcp serve

Start the server

uv run youtube-insights-mcp login [--email] [--manual]

Sign in as channel owner

uv run youtube-insights-mcp doctor

Check config and API access

uv run youtube-insights-mcp gen-token

Generate a secure token


Deploy

Docker

docker build -t youtube-insights-mcp .
docker run -d -p 8080:8080 --env-file .env \
  -v ./data:/app/data -v ./secrets:/app/secrets:ro \
  youtube-insights-mcp

The image runs as a non-root user and has a health check at GET /healthz. The same image works on Google Cloud Run, Fly.io, Railway and Render. Mount /app/data on a volume so the cache and sign-in survive restarts.


Troubleshooting

Problem

Fix

Error 403: org_internal

Your consent screen is Internal. Switch it to External โ†’ Testing and add yourself as a test user

redirect_uri_mismatch

Add exactly http://localhost:8765/oauth2callback to the OAuth client

Access blocked / app not verified

Add your account under Test users, then click Advanced โ†’ Continue

Login uses the wrong Google account

Use login --email you@gmail.com and pick the right account in the chooser

No Google sign-in stored

Run login, and run serve from the same folder (or set an absolute YTMCP_DATA_DIR)

update_video_metadata is missing

Set YTMCP_ENABLE_WRITE_TOOLS=true, run login again, restart serve and reconnect your client

quotaExceeded

Google's 10,000 units/day are used up. Cached answers still work; quota resets at midnight Pacific

Port 8080 already in use

Set YTMCP_PORT=8081, or stop the old process


Security

  • Auth modes: none only starts on 127.0.0.1. token requires 32+ character tokens, compared in constant time. google uses OAuth 2.1 with PKCE and dynamic client registration.

  • Google tokens stay on the server. Clients only receive a token signed by this server.

  • Read-only by default. The edit permission is requested only when you enable write tools, and every edit needs a preview and your confirmation.

  • Private files: the sign-in file is stored with owner-only permissions, and .env, secrets/ and data/ are git-ignored.

  • Quota guard: a local daily budget stops runaway agents from using up your quota.

Found a vulnerability? Please open a private security advisory on GitHub instead of a public issue.


Development

uv sync                       # install with dev tools
uv run pytest                 # offline tests (HTTP mocked)
uv run ruff check .           # lint
uv run python scripts/smoke_test.py @somechannel   # live test against a running server
src/youtube_insights_mcp/
โ”œโ”€โ”€ cli.py            # serve | login | doctor | gen-token
โ”œโ”€โ”€ config.py         # settings from .env + validation
โ”œโ”€โ”€ auth.py           # token / Google OAuth / allowlist
โ”œโ”€โ”€ google_oauth.py   # owner login (PKCE) + auto refresh
โ”œโ”€โ”€ youtube_api.py    # async Data + Analytics client, retries, quota, cache
โ”œโ”€โ”€ storage.py        # SQLite: cache, snapshots, Studio metrics, quota
โ”œโ”€โ”€ analysis.py       # channel report and velocity
โ”œโ”€โ”€ server.py         # FastMCP app, stateless Streamable HTTP
โ””โ”€โ”€ tools/
    โ”œโ”€โ”€ public_tools.py
    โ””โ”€โ”€ owner_tools.py

Contributing

Pull requests are welcome. Please run uv run pytest and uv run ruff check . before opening one. For larger changes, open an issue first so we can agree on the approach.


License

MIT ยฉ Rahees Ahmed

If this project helps you, please give it a โญ on GitHub. It helps others find it.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelogโ€ฆ

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables Claude to access and manage YouTube channel data through the YouTube Data API v3 and YouTube Analytics API. Provides tools for reading analytics, fetching video metadata, searching uploads, and updating video SEO directly from Claude.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables Claude to directly analyze YouTube channel performance by fetching real metrics such as views, watch time, retention, traffic sources, reach/CTR, and comments via YouTube APIs.
      23 npm
      MIT
    • F
      license
      A
      quality
      C
      maintenance
      Enables Claude to retrieve YouTube transcripts, search videos and channels, fetch metadata and playlists, analyze engagement, and access trending content via natural language.
      15
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables Claude Code to search YouTube, retrieve video transcripts and metadata, explore channels, playlists, comments, and trending videos, and analyze engagement and replayed segments.
      18 npm
      -