YouTube Insights MCP
Connects to the YouTube Data API v3 to analyze any public channel: channel profiles and totals, full upload lists with tags and stats, video metadata and comments, Shorts vs long-form detection, upload cadence and best posting times, winning title words and top tags, side-by-side channel comparisons, view velocity, and niche video/channel search.
Connects to the YouTube Analytics API to surface the private analytics of the channel owner's own channel: engaged views, average percentage viewed, watch time, subscribers gained per video, retention curves with steepest drop-off, and audience breakdowns by country, age and gender, traffic source, device and subscription status. Also lets you record metrics that only YouTube Studio exposes (Shorts viewed vs swiped away, impressions, CTR) and, when explicitly enabled, preview and confirm edits to video titles, descriptions and tags.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
YouTube Insights MCP
Ask Claude anything about any YouTube channel, including the private analytics of your own.

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 |
Quick start
What you need
uv (installs Python for you)
A Google account and a free Google Cloud project
Step 1: Get Google credentials
In Google Cloud Console, create a project.
APIs & Services โ Library: enable YouTube Data API v3 and YouTube Analytics API.
Credentials โ Create credentials โ API key. Copy the key.
(Only for your own analytics) Credentials โ Create credentials โ OAuth client ID โ Web application
Authorized redirect URI:
http://localhost:8765/oauth2callbackDownload the JSON and save it as
secrets/google_client_secret.json
(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 syncCopy the example config:
cp .env.example .env # macOS / Linux
copy .env.example .env # WindowsOpen .env and set at least:
YTMCP_YOUTUBE_API_KEY=your-api-key
YTMCP_BEARER_TOKENS=paste-output-of-gen-tokenuv run youtube-insights-mcp gen-token # creates a random access token
uv run youtube-insights-mcp doctor # checks your setupStep 3: (Optional) Sign in for your own analytics
uv run youtube-insights-mcp login --email you@gmail.comPick 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/mcpConnect 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.
Expose the server, for example with
cloudflared tunnel --url http://localhost:8080, or deploy it.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.comAdd
https://your-public-host/auth/callbackto the OAuth client's redirect URIs.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 |
| Subscribers, views, video count, description, keywords, topics | 1โ2 |
| Every upload with title, tags, stats, duration and Short flag | ~1 / 25 videos |
| Full metadata for up to 50 videos | 1 |
| Top comments with likes and replies | 1 |
| Shorts vs long, upload cadence, best hour/weekday, winning title words, top tags, outliers | ~1 / 25 videos |
| 2โ6 channels side by side | per channel |
| Views per hour since the last check | ~1 / 25 videos |
| Find videos or channels in a niche | 100 |
| Quota used today and remaining | 0 |
Your channel (needs login or Google mode)
Tool | What it does |
| Your channel profile and totals |
| Per video: views, engaged views, avg % viewed, watch time, likes, shares, subscribers |
| By country, age & gender, traffic source, device, subscribed status, content type or day |
| 100-point retention curve, the steepest drop, and comparison with similar videos |
| Any YouTube Analytics metrics, dimensions and filters |
| Save numbers only Studio shows (Shorts viewed vs swiped, impressions, CTR) |
| Edit title, description or tags with preview + confirm (only when |
Good to know: no Google API gives the Shorts viewed vs swiped away percentage directly.
engagedViews รท viewsfromget_my_video_performanceis a close stand-in.
Configuration
All settings live in .env. See .env.example for the full list.
Variable | Default | Description |
| required | Google Cloud API key |
|
| OAuth client JSON (for your analytics) |
|
|
|
| Comma-separated tokens, 32+ characters each | |
| Public | |
| Random 32+ characters (google mode) | |
| anyone | Google accounts allowed in (google mode) |
|
| Listen address |
|
| SQLite cache and sign-in token |
|
| Max Data API units per day |
|
| How long API responses are reused |
|
| Allow editing your videos (run |
Commands
Command | Purpose |
| Start the server |
| Sign in as channel owner |
| Check config and API access |
| 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-mcpThe 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 |
| Your consent screen is Internal. Switch it to External โ Testing and add yourself as a test user |
| Add exactly |
| Add your account under Test users, then click Advanced โ Continue |
Login uses the wrong Google account | Use |
| Run |
| Set |
| Google's 10,000 units/day are used up. Cached answers still work; quota resets at midnight Pacific |
Port 8080 already in use | Set |
Security
Auth modes:
noneonly starts on127.0.0.1.tokenrequires 32+ character tokens, compared in constant time.googleuses 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/anddata/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 serversrc/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.pyContributing
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โฆ
This server cannot be deployed
Maintenance
Related MCP Connectors
AI YouTube analyst in Claude for creators: audit, fix, decide what to make next, grow subs.
Your YouTube channelsโ private analytics for AI assistants: revenue, views, retention. Read-only.
YouTube for AI agents: transcripts, comments, video stats, channel monitor, Shorts captions.
Your YouTube library in Claude, ChatGPT and Cursor: transcripts, breakdowns, summaries, search.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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.1MIT
- AlicenseNot gradedqualityDmaintenanceEnables 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 npmMIT
- FlicenseAqualityCmaintenanceEnables Claude to retrieve YouTube transcripts, search videos and channels, fetch metadata and playlists, analyze engagement, and access trending content via natural language.15-
- FlicenseNot gradedqualityCmaintenanceEnables 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-