YouTube MCP Connector for Claude.ai

Production remote MCP server that lets Claude.ai use read-only YouTube tools over HTTPS:

• search_videos

• get_trending_videos

• get_channel_videos

• get_video_details

• get_engagement_stats

• get_transcript

• search_transcript

The service uses the official YouTube Data API v3 for search, metadata, trending, and channel uploads. Transcript retrieval is best-effort: it tries public InnerTube caption tracks first, then YouTube watch-page caption discovery. It does not bypass CAPTCHA, blocks, or rate limits.

Local Setup

npm install
cp .env.example .env

Set at minimum:

YOUTUBE_API_KEY=your_google_api_key
AUTH_MODE=none

Run locally:

npm run dev

Health checks:

curl http://localhost:3000/health
curl http://localhost:3000/ready

Build and test:

npm test
npm run build

Related MCP server: youtube-research

Production Environment

Minimum Railway test variables:

YOUTUBE_API_KEY=...
AUTH_MODE=none

Redis is recommended, but the app can boot without it and will use an in-process no-op cache.

Full production variables:

NODE_ENV=production
YOUTUBE_API_KEY=...
AUTH_MODE=oauth
AUTH_ISSUER=https://YOUR_AUTH0_DOMAIN/
AUTH_AUDIENCE=https://youtube-claude-mcp
AUTH_JWKS_URL=https://YOUR_AUTH0_DOMAIN/.well-known/jwks.json
AUTH_REQUIRED_SCOPE=youtube:read
REDIS_URL=...

Default cache TTLs:

TRANSCRIPT_CACHE_TTL_SECONDS=604800
VIDEO_DETAILS_CACHE_TTL_SECONDS=900
TRENDING_CACHE_TTL_SECONDS=600
CHANNEL_VIDEOS_CACHE_TTL_SECONDS=600

Auth0 Setup

1. Create or reuse an Auth0 API.

2. Set the API identifier to the same value as AUTH_AUDIENCE.

3. Add scope youtube:read.

4. Use the Auth0 issuer URL as AUTH_ISSUER.

5. Use the tenant JWKS endpoint as AUTH_JWKS_URL.

6. Configure Claude.ai custom connector OAuth advanced settings with the appropriate Auth0 client details.

The /mcp endpoint requires a valid Authorization: Bearer <token> when AUTH_MODE=oauth.

Railway Deployment

1. Push the repository to GitHub.

2. Create a Railway project from the GitHub repository.

3. Railway should use the checked-in Dockerfile via railway.json.

4. Add service variables:

YOUTUBE_API_KEY=...
AUTH_MODE=none

5. Deploy and open /health.

6. Add Railway Redis later if you want shared caching, then set REDIS_URL.

7. Switch to Auth0 by setting AUTH_MODE=oauth and the Auth0 variables.

Render Deployment

1. Create a Render Redis instance.

2. Create a Render Web Service from this repository.

3. Select Docker deployment.

4. Add the production environment variables.

5. Deploy.

6. Verify:

curl https://YOUR_RENDER_URL/health
curl https://YOUR_RENDER_URL/ready
curl -i https://YOUR_RENDER_URL/mcp

Unauthenticated /mcp should return 401.

Claude.ai Connector

1. Open Claude.ai settings.

2. Go to Customize, then Connectors.

3. Add a custom connector.

4. Use:

https://YOUR_RENDER_URL/mcp

5. Configure OAuth advanced settings if production auth is enabled.

6. Enable the connector in a chat.

Demo prompts:

• Search YouTube for 5 recent MCP server tutorials.

• What are the most popular videos in Pakistan right now?

• Show the latest videos from @GoogleDevelopers.

• Get views, likes and duration for this YouTube URL.

• Calculate its engagement rate.

• Get the transcript and summarize it.

• Where in the transcript do they mention authentication?

Operational Notes

• Restrict and rotate the YouTube API key in Google Cloud where practical.

• Do not log API keys, bearer tokens, or full authorization headers.

• Search calls are quota-expensive; prefer channel uploads and cached metadata where possible.

• Redis failures degrade cache behavior but do not fail normal tool calls.

• Transcript failures can happen when captions are disabled, unavailable, region-restricted, or blocked by YouTube.

• CAPTCHA or bot-block responses are surfaced as errors; the service does not attempt bypasses.

Troubleshooting

• Startup fails with YOUTUBE_API_KEY is required: set the server-side API key.

• Startup fails in production with REDIS_URL is required: attach Render Redis and set its URL.

• /mcp returns 401: token is missing, expired, malformed, or signed by the wrong issuer.

• /mcp returns 403: token is valid but lacks youtube:read.

• Transcript tool returns unavailable: the video may not have public captions.

• YouTube quota exceeded: wait for quota reset, request a quota increase, or reduce search usage.