MCP 服务器

tubemind-secure-mcp

YouTube intelligence MCP server providing 18 tools for research, analytics, benchmarking, and content strategy, with OAuth2 and encrypted token storage.

README

<h1 align="center">tubemind-secure-mcp</h1>

YouTube intelligence, powered by Claude. Secure by design. Model Context Protocol server with 18 tools for YouTube research, analytics, benchmarking and content strategy.

📦 18 tools · 🔐 OAuth2 + AES-256-GCM · 🛡️ OWASP Top 10 · 🤖 Claude Desktop ready

🎯 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