yt-mcp — YouTube MCP Server

MCP server quản lý kênh YouTube (Data API v3 + Analytics), kiến trúc stateless theo tinh thần Facebook MCP: server không lưu token người dùng. Client giữ refresh token, server đổi ra access token và cache RAM theo sha256(refresh_token).

Xem thiết kế chi tiết + lý do từng quyết định: docs/thiet-ke.md.

Kiến trúc

server.py       → khai báo tool @mcp.tool() (passthrough mỏng)
manager.py      → điều phối, ráp tham số
youtube_api.py  → gọi Data API v3 + Analytics (google-api-python-client)
auth.py         → refresh→access + cache theo hash(refresh token)
jobs.py         → upload async in-memory (job)
web.py          → route /auth, /auth/callback, /upload
config.py       → scope + hằng số
run_http.py     → streamable-http (stateless) + gắn route web

Related MCP server: yt-fetch

Chuẩn bị Google Cloud (1 lần)

1. Tạo project ở Google Cloud Console (tài khoản hoangtuanbka93@gmail.com).

2. Bật YouTube Data API v3 và YouTube Analytics API.

3. OAuth consent screen: External → Publish app → In production (chấp nhận "unverified"; nếu Testing thì refresh token chết sau 7 ngày).

4. Tạo OAuth client ID kiểu Web application. Thêm Authorized redirect URI: https://<host>.<tailnet>.ts.net/auth/callback.

5. Lấy client_id + client_secret.

Cấu hình & chạy

Tạo file .env cạnh compose.yaml:

GOOGLE_CLIENT_ID=xxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=xxx
PUBLIC_BASE_URL=https://my-host.tailnet-name.ts.net

docker compose up -d --build

• Endpoint MCP: https://<host>.<tailnet>.ts.net/mcp

• Trang lấy token: https://<host>.<tailnet>.ts.net/auth

• Trang đẩy file: https://<host>.<tailnet>.ts.net/upload

Lấy refresh token (1 lần)

Mở https://<host>.<tailnet>.ts.net/auth bằng browser → đồng ý (bấm qua cảnh báo "unverified app" 1 lần) → trang hiện refresh token → copy.

Khai báo ở MCP client

"yt-mcp": {
  "url": "https://<host>.<tailnet>.ts.net/mcp",
  "headers": { "x-youtube-refresh-token": "1//dán_refresh_token_ở_đây" }
}

Quản nhiều kênh = khai báo nhiều kết nối, mỗi cái một refresh token khác.

Upload video

source của youtube_video_upload nhận 3 dạng:

Upload chạy nền → trả job_id → poll bằng youtube_upload_status(job_id).

Danh sách tool (~30)

• Channel: youtube_channel_get (bỏ trống = whoami), youtube_channel_update

• Video: youtube_video_get, youtube_video_list_mine, youtube_video_update, youtube_video_delete, youtube_video_rate, youtube_video_set_privacy

• Upload: youtube_video_upload, youtube_upload_status

• Search: youtube_search

• Comment: youtube_comment_list, youtube_comment_thread_get, youtube_comment_reply, youtube_comment_moderate, youtube_comment_delete

• Playlist: youtube_playlist_create/list/get/update/delete, youtube_playlist_items, youtube_playlist_item_add/remove

• Analytics: youtube_analytics_video/channel/top_videos

Ràng buộc đã biết

• Quota dùng chung: 1 OAuth app = 10.000 unit/ngày cho mọi client (upload=1.600/lần). Chạm trần thì xin Google nâng quota.

• Upload file client-local luôn 2 bước (đẩy file → gọi tool).

• Job upload lưu in-memory → mất khi restart container.