youtube-mcp

An MCP server that lets you analyze @ザビエル-zav's YouTube channel directly from Claude. It aims to answer questions like "Which video had the best CTR last week?" by fetching real data.

Built with Node.js (no Python). It wraps the YouTube Analytics API / Reporting API / Data API v3 with the official Node libraries (googleapis, google-auth-library) and exposes them as tools via the official MCP TypeScript SDK (@modelcontextprotocol/sdk).

APIs used and how they are divided

Only CTR has a fundamentally different retrieval method (bulk reports), so it follows a separate path: register-reach-job.js registers the job → download-reports.js periodically accumulates CSVs locally.

Related MCP server: youtube-organic-mcp

Setup

1. Google Cloud Console

1. Create a project

2. Enable the following 3 APIs

   • YouTube Analytics API

   • YouTube Reporting API

   • YouTube Data API v3

3. Configure the OAuth consent screen (user type = External, add your own Google account as a test user)

4. Credentials > OAuth client ID > Create one with application type = Desktop app, and download the JSON

5. Place the downloaded JSON in the root of this repository under the name client_secret.json

   Never commit client_secret.json or the token.json created after the first authentication. It is already in .gitignore, but be careful not to run git add -f by mistake.

2. Node.js and dependencies

Node.js 18 or later is required (if not installed, install the LTS version from nodejs.org. The installer includes npm, so no separate PATH configuration is needed like with Python).

npm install

3. Register the reach report (CTR) job — run this first

The Reporting API starts generating data from the day the job is registered, and historical data can only go back 30 days from the registration point. The longer you delay registration, the more past CTR data is lost, so run this before anything else.

npm run register-reach-job

On the first run, a browser opens and asks for authentication (after that, token.json handles automatic renewal).

4. Start the MCP server

npm start

To use it from Claude Desktop, register it in claude_desktop_config.json as follows.

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

5. Download reach reports (a few hours to 2 days after registration)

npm run download-reports

CSVs are accumulated under data/reach/<report_type>/. Reports disappear on YouTube's side after 60 days (30 days for historical data), so keep running this regularly (ideally once a day). On Windows, use Task Scheduler; on Mac/Linux, set up a cron job. The get_reach tool reads these local CSVs.

List of exposed tools

Output is not raw JSON but rounded numbers and text tables capped at about 20 entries (to reduce context consumption on the Claude side).

Known limitations

• Analytics API data lags up to about 2 days behind what YouTube Studio shows. "Yesterday's numbers" may not be available.

• get_reach only looks at CSVs already downloaded locally. Data for periods when download-reports.js was not run will not appear.

• The exact column structure of channel_reach_basic_a1 / channel_reach_combined_a1 is unconfirmed. get_reach has a fallback that guesses column names by keyword, but check once against the headers of an actually downloaded CSV.

• No write scopes are attached (read-only). There is no path that could accidentally modify or delete videos.

Deployment target branches

If you also want to use it from mobile, the quickest path is to switch StdioServerTransport to StreamableHTTPServerTransport (@modelcontextprotocol/sdk/server/streamableHttp.js) and piggyback on your existing hosting environment.