🎯 Why tubemind-secure-mcp?
Turn Claude into a YouTube growth strategist — without ever handing it your raw OAuth tokens.
- ⚡ Plug-and-play with Claude Desktop — drop one config block, get 18 production tools.
- 🔐 Secure by default — tokens encrypted at rest (AES-256-GCM), SSRF guard, rate limiting, audit log, Zod-validated inputs. OWASP Top 10 mapped end-to-end.
- 📊 Real data, not scraping — official YouTube Data API v3 + YouTube Analytics API. Brand Accounts supported.
- 🧠 Beyond raw API — built-in heuristics for CTR, retention, keyword difficulty, content gaps, hook angles and N-day content calendars.
- 🪶 Tiny footprint — 3 runtime deps (
@modelcontextprotocol/sdk,googleapis,zod). Node ≥ 20.
✨ Overview
tubemind-secure-mcp is a Model Context Protocol (MCP) server that gives Claude Desktop (and any MCP client) 18 production-grade tools for working with YouTube:
- 🔍 Search & SEO — trending topics, keyword stats, tag suggestions
- 📺 Video & Channel — list videos, read/update metadata, get tags
- 📊 Analytics — channel analytics (views, watch time, retention) via YouTube Analytics API
- 🏆 Benchmark — compare your channel against competitors
- 🧠 Heuristics — keyword difficulty, title patterns, content gaps, hook angles, CTR potential, retention signals, content calendar
- 🕵️ Competitor research — competitor video discovery
Built secure by design: OAuth2 (Brand Account ready), AES-256-GCM token encryption at rest, SSRF guard, rate limiting, audit logging, Zod input validation — mapped to OWASP Top 10.
📦 Installation
# Global install
npm install -g tubemind-secure-mcp
# Or run on demand
npx tubemind-secure-mcp
Requires Node.js ≥ 20.
🔐 OAuth Setup (one-time)
YouTube APIs need an OAuth2 token. The package ships with an auth server that walks you through it.
1) Create OAuth credentials in Google Cloud
- Go to Google Cloud Console → APIs & Services → Credentials
- Enable YouTube Data API v3 and YouTube Analytics API
- Create OAuth 2.0 Client ID → Web application
- Authorized redirect URI:
http://localhost:4000/oauth/callback - Copy the Client ID and Client Secret
2) Configure environment
Copy .env.example to .env and fill in:
YOUTUBE_CLIENT_ID=your-client-id.apps.googleusercontent.com
YOUTUBE_CLIENT_SECRET=your-client-secret
YOUTUBE_REDIRECT_URI=http://localhost:4000/oauth/callback
# Generate with: openssl rand -hex 32
TOKEN_ENCRYPTION_KEY=your-64-char-hex-key
RATE_LIMIT_PER_MINUTE=60
REQUEST_TIMEOUT_MS=10000
AUDIT_LOG_PATH=./logs/audit.log
NODE_ENV=production
3) Run the OAuth flow
pnpm auth
# or: npx tsx --env-file=.env src/auth-server.ts
Open http://localhost:4000, sign in with the Google account that owns the channel (Brand Accounts supported), authorize, and the encrypted token is saved to ./tokens/youtube.token.json.
🤖 Use with Claude Desktop
Add to claude_desktop_config.json:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"tubemind": {
"command": "npx",
"args": ["-y", "tubemind-secure-mcp"],
"env": {
"YOUTUBE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
"YOUTUBE_CLIENT_SECRET": "your-client-secret",
"YOUTUBE_REDIRECT_URI": "http://localhost:4000/oauth/callback",
"TOKEN_ENCRYPTION_KEY": "your-64-char-hex-key",
"RATE_LIMIT_PER_MINUTE": "60",
"REQUEST_TIMEOUT_MS": "10000",
"AUDIT_LOG_PATH": "./logs/audit.log",
"NODE_ENV": "production"
}
}
}
}
Restart Claude Desktop. The 18 tools will appear automatically.
🛠️ Tools
| Category | Tool | Description |
|---|---|---|
| Search | search_trending_topics | Discover trending topics by region/category |
get_keyword_stats | Search volume signals for keywords | |
suggest_tags | Tag recommendations from a seed | |
| Video | get_video_tags | Read tags from a video |
update_video_metadata | Update title/description/tags (write scope) | |
list_channel_videos | Paginate channel uploads | |
| Analytics | get_channel_analytics | Views, watch time, retention (Analytics API) |
score_best_publish_window | Best day/hour heatmap to publish | |
| Benchmark | benchmark_channel | Compare channel vs. peers |
| Heuristics | estimate_keyword_difficulty | Difficulty score 0–100 |
analyze_title_patterns | Common patterns in top videos | |
detect_content_gaps | Topics competitors cover that you don't | |
| Heuristics+ | estimate_ctr_potential | CTR estimate from title/thumbnail signals |
suggest_hook_angles | Hook angles for a topic | |
find_trending_keywords | Rising-momentum keywords | |
analyze_retention_signals | Retention-shaping factors | |
generate_content_calendar | N-day content plan | |
| Competitor | get_competitor_videos | Top videos from a competitor channel |
All inputs are validated with Zod. All errors return safe messages (stack traces only when NODE_ENV=development).
🔒 Security
tubemind-secure-mcp is built secure-by-default. See SECURITY.md for the full posture mapped to OWASP Top 10.
| Control | Implementation |
|---|---|
| A01 — Broken Access Control | OAuth2 scopes least-privilege, audit log per call |
| A02 — Cryptographic Failures | AES-256-GCM at rest for tokens, secrets via env only |
| A03 — Injection | Zod schemas on every tool input |
| A04 — Insecure Design | Rate limit, request timeout, SSRF guard (host whitelist) |
| A05 — Misconfiguration | .env.example template, no defaults that leak |
| A07 — AuthN Failures | OAuth2 PKCE-style flow, encrypted token storage |
| A08 — Software/Data Integrity | Pinned deps, pnpm audit in CI, dependabot |
| A09 — Logging Failures | Audit log of every tool call (timestamp, tool, success) |
| A10 — SSRF | Outbound calls restricted to googleapis.com family |
Found a vulnerability? Email wleandro.oliveira@gmail.com — 72h response.
🧰 Local development
pnpm install
pnpm dev # tsx watch on src/index.ts
pnpm build # tsc → dist/
pnpm typecheck
pnpm test
pnpm audit:security
📜 License
MIT © Wanderson Leandro de Oliveira / Dewtech