youtube-analytics-mcp

A local, read-only MCP server that gives Claude access to your YouTube channel's private Analytics data — views, watch time, retention, subscribers, traffic sources, audience demographics, revenue, and thumbnail impressions/CTR. Not just what any public API key can already see.

Nothing in this server can edit, upload, publish, or delete anything on your channel. See SECURITY.md for the full security review.

Requirements

• Node.js 22+
• A Google account that owns (or manages) the YouTube channel you want data for
• macOS, Linux, or WSL (the npm run auth browser flow uses the open command)

Setup checklist

Follow these in order. Steps 1–4 happen in Google Cloud Console; steps 5–8 happen on your machine.

1. Create a Google Cloud project

Go to console.cloud.google.com and create a new project (or pick an existing one you're comfortable using).

2. Enable three APIs

In your project, go to APIs & Services → Library and enable each of these:

• [ ] YouTube Data API v3
• [ ] YouTube Analytics API
• [ ] YouTube Reporting API (only needed for thumbnail impressions/CTR — see below)

3. Configure the OAuth consent screen

Go to APIs & Services → OAuth consent screen.

• [ ] User type: External (unless you have a Google Workspace account, in which case Internal also works)
• [ ] Fill in the required app name / support email fields
• [ ] Add the Analytics scopes when prompted (or skip — the app requests them directly, this screen just needs to exist)
• [ ] Publish the app to Production. This is the step people skip and then hit a wall: apps left in "Testing" mode only allow sign-in from accounts you've explicitly added as test users, and their refresh tokens expire after 7 days, meaning you'd have to redo step 6 every week. Publishing to Production (without submitting for Google's verification review) is fine for a personal tool — Google will show an "unverified app" warning when you sign in, and you click Advanced → Go to [your app name] (unsafe) to proceed. That's expected and safe for your own app.

4. Create OAuth credentials

Go to APIs & Services → Credentials → Create Credentials → OAuth client ID.

• [ ] Application type: Desktop app
• [ ] Give it any name
• [ ] Copy the Client ID and Client Secret it generates — you'll need them in step 5

No redirect URI needs to be registered here; this server binds an ephemeral local port at auth time and Google accepts any loopback address for Desktop-type clients.

5. Install and build

git clone <this-repo-url>
cd youtube-analytics-mcp
npm install
npm run build

6. Configure your credentials

cp .env.example .env

Edit .env and paste in the Client ID / Client Secret from step 4:

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret

.env is gitignored — it will never be committed. Optional settings:

• GOOGLE_API_KEY — not required for any current tool, leave blank unless you extend the server yourself.
• REVENUE_CURRENCY — defaults to USD. Set to your AdSense payout currency (e.g. BRL) if you'd rather see revenue figures in that currency; Google converts server-side.

7. Authenticate

npm run auth

This opens your browser for Google sign-in and stores a refresh token at ~/.youtube-analytics-mcp/token.json (permissions locked to your user only, never in the repo). You only need to do this once — the server refreshes the access token automatically afterward.

Verify it worked:

npm run auth:status

You should see Authenticated and your channel's name.

8. Point Claude Code at it

Add to your MCP config, using the absolute path to this project's dist/index.js:

{
  "mcpServers": {
    "youtube-analytics-channel": {
      "command": "node",
      "args": ["/absolute/path/to/youtube-analytics-mcp/dist/index.js"]
    }
  }
}

Restart Claude Code (or reload MCP servers) and you should see the tools below available.

Available tools

Tool	What it does
health_check	Confirms the server is up.
get_channel_overview	Views, watch time, retention, subscribers, revenue for a date range or preset (last_7_days/last_28_days/last_90_days/last_365_days).
list_videos	Uploaded videos with metadata, filterable by publish date range and long-form vs. Shorts.
get_video_analytics	Deep-dive analytics for one video.
get_top_videos	Rank videos by any metric (views, watch time, retention, subscribers, revenue, impressions, CTR).
get_daily_performance	Day-by-day time series.
get_traffic_sources	Views/watch time by traffic source (search, suggested, Shorts feed, external, etc.), channel-wide or per video.
get_audience_breakdown	Audience by country, age group, or gender.
get_revenue_analytics	Revenue totals or breakdown by video/day. Returns available: false rather than fabricating numbers if revenue data isn't accessible.
compare_periods	Two date ranges compared, with absolute + percentage change.
get_impressions_and_ctr	Thumbnail impressions and click-through rate. Async — see below.
run_custom_report	Escape hatch for ad-hoc queries, restricted to an allowlist of metrics/dimensions.

A note on impressions and CTR

YouTube does not expose thumbnail impressions or CTR through the interactive Analytics API (reports.query) under any dimension/filter combination — this was verified directly against the API, not assumed from docs. That data only exists in YouTube's bulk "Reach report", a separate async job API:

1. The first call to get_impressions_and_ctr registers a recurring reporting job with Google.
2. Google takes 24–48 hours to produce the first report, then continues producing new ones roughly daily.
3. Every call to get_impressions_and_ctr (or get_top_videos sorted by impressions/CTR) syncs any newly available reports into a local cache at ~/.youtube-analytics-mcp/reach-cache.json, then answers from that cache.

Until the first report lands, these tools return impressions: 0, impressionsCtr: null, and a note explaining why. This is expected on first use, not a bug.

Troubleshooting

• "Access blocked" during npm run auth: your OAuth consent screen is still in Testing mode. Go back to step 3 and either add your account as a test user or publish to Production.
• NotAuthenticatedError on server start: run npm run auth.
• Revenue always 0: either the channel isn't monetized, or the numbers are genuinely zero for that period. The tool never fabricates revenue — check get_revenue_analytics's available field for a real permission/access failure vs. real zeros.
• get_impressions_and_ctr / impressions-sorted get_top_videos return nothing: check dataCoverage in the response. If earliestDate is null, the bulk report job hasn't produced its first report yet (can take up to 48h after the very first call).

Testing

npm test

Runs unit tests (Node's built-in test runner) covering date/period validation, ISO-8601 duration parsing, CSV parsing, Analytics report row mapping, and period-comparison math (including the zero-division edge case). These are pure-function tests only — they don't mock live Google API calls or OAuth token refresh; those paths were validated manually against a real channel during development.

Security

See SECURITY.md for the full threat model and OWASP Top 10 review. Short version: everything is read-only, all secrets stay on your machine outside the repo, and every user-supplied value that reaches a Google API call is validated first.

License

MIT — see LICENSE.