io.github.dewtech-technologies/tubemind-secure-mcp
Secure MCP server for YouTube intelligence — 18 tools, OAuth2, OWASP Top 10 controls.
Open source Open in the app JSON README (API)
About
Secure MCP server for YouTube intelligence — 18 tools, OAuth2, OWASP Top 10 controls.
Details
- Kind
- MCP servers
- Topic
- Social & content
- Publisher
- dewtech-technologies
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.3
- Open pull requests
- 5
- Last push
- 2026-07-13T12:09:14Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:42
- Updated
- 2026-08-29 03:02:42
- Origin id
io.github.dewtech-technologies/tubemind-secure-mcp
README
<h1 align="center">tubemind-secure-mcp</h1>
<p align="center">
<b>YouTube intelligence, powered by Claude. Secure by design.</b><br/>
Model Context Protocol server with 18 tools for YouTube research, analytics, benchmarking and content strategy.
</p>
<p align="center">
<a href="https://www.npmjs.com/package/tubemind-secure-mcp"><img src="https://img.shields.io/npm/v/tubemind-secure-mcp?style=flat-square&color=CB3837&logo=npm" alt="npm version"/></a>
<a href="https://www.npmjs.com/package/tubemind-secure-mcp"><img src="https://img.shields.io/npm/dm/tubemind-secure-mcp?style=flat-square" alt="downloads"/></a>
<a href="https://github.com/dewtech-technologies/tubemind-secure-mcp/blob/main/SECURITY.md"><img src="https://img.shields.io/badge/security-OWASP_Top_10-5A67D8?style=flat-square" alt="OWASP"/></a>
<a href="https://github.com/dewtech-technologies/tubemind-secure-mcp/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/tubemind-secure-mcp?style=flat-square&color=blue" alt="MIT License"/></a>
<a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-1.26-5A67D8?style=flat-square" alt="MCP SDK"/></a>
</p>
<p align="center">
<b>📦 18 tools · 🔐 OAuth2 + AES-256-GCM · 🛡️ OWASP Top 10 · 🤖 Claude Desktop ready</b>
</p>
---
## 🎯 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
```bash
# 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](https://console.cloud.google.com/apis/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:
```bash
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
```bash
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`
```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](./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
```bash
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](https://github.com/wleandrooliveira) / [Dewtech](https://github.com/dewtech-technologies)