io.github.dewtech-technologies/tubemind-secure-mcp

---

🎯 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

1. Go to Google Cloud Console → APIs & Services → Credentials
2. Enable YouTube Data API v3 and YouTube Analytics API
3. Create OAuth 2.0 Client ID → Web application
4. Authorized redirect URI: http://localhost:4000/oauth/callback
5. 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