social-video-mcp

MCP server that gives AI agents the ability to play videos from YouTube and TikTok, browse your accounts, and control playback — all through a lightweight mpv player window.

Built for Claude Code and any MCP-compatible client.

https://github.com/user-attachments/assets/08ddb1b3-ed0f-4de3-b465-c0b58ebfa894

Features

Playback — Play videos from YouTube or TikTok in a native mpv window with full remote control:

• Play, pause, stop, seek
• Playlist playback with next/prev navigation and shuffle
• Queue videos without interrupting current playback
• Audio-only mode for podcasts and music while you code
• Authenticated playback via browser cookies (age-restricted, private videos)

Smart Recommendations — Ask for similar content based on what's currently playing. Finds related videos and queues them automatically.

Infinite Playlists — TikTok and YouTube Shorts playlists auto-refill as you watch. Never runs out.

YouTube Account — Browse your YouTube account directly from your AI agent:

• Subscription feed, liked videos, watch later, history
• List subscribed channels
• Browse channel uploads and Shorts
• Search YouTube with personalized results

TikTok — Browse and play TikTok content:

• Fetch videos from any TikTok user profile
• Play a user's videos as a continuous playlist

Multi-Browser Support — Switch between Chrome, Firefox, Brave, Edge, Safari, Opera, Chromium, or Vivaldi for cookie-based authentication.

Video Info — Fetch metadata without playing: title, description, chapters, duration, tags, view/like counts.

Prerequisites

brew install mpv yt-dlp

• mpv — Lightweight video player
• yt-dlp — Video stream resolver and cookie extractor
• A supported browser — Logged into YouTube/TikTok (Chrome, Firefox, Brave, Edge, Safari, Opera, Chromium, Vivaldi)
• Node.js >= 18

Installation

git clone https://github.com/ronantakizawa/social-video-mcp.git
cd social-video-mcp
npm install
npm run build

Configuration

Add to your Claude Code config (~/.claude.json):

{
  "mcpServers": {
    "social-video": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/social-video-mcp/dist/index.js"]
    }
  }
}

Then restart Claude Code.

Tools

Playback

Tool	Description
play_video	Play a YouTube or TikTok video. Optional timestamp and audio_only mode.
play_audio	Play audio only — no video window. Great for podcasts and music.
play_playlist	Play an entire YouTube playlist. Optional shuffle.
queue_video	Add a video to the queue without interrupting current playback.
pause_video	Toggle pause/resume.
stop_video	Stop playback and close the player window.
seek_video	Seek to an absolute position in seconds.
next_video	Skip to the next video in a playlist.
prev_video	Go back to the previous video in a playlist.
get_status	Get current playback state: title, position, duration, paused.

Smart Features

Tool	Description
play_similar	Find and play/queue videos similar to what's currently playing.

YouTube Account

Tool	Description
get_youtube_feed	Fetch your subscription feed, liked videos, watch later, or history.
get_subscribed_channels	List your subscribed YouTube channels.
get_channel_videos	List recent uploads from a specific channel.
get_channel_shorts	List recent Shorts from a specific channel.
get_subscription_shorts	Fetch recent Shorts from your subscribed channels.
play_shorts	Play Shorts as a continuous auto-advancing playlist.
search_youtube	Search YouTube with personalized results.

TikTok

Tool	Description
get_tiktok_user_videos	Fetch recent videos from a TikTok user profile.
play_tiktok_user	Play a TikTok user's videos as an infinite continuous playlist.

Settings

Tool	Description
set_browser	Switch browser for cookie auth (chrome, firefox, brave, edge, safari, opera, chromium, vivaldi).
get_browser	Check which browser is currently active.
get_video_info	Fetch full video metadata from YouTube or TikTok.

How It Works

• Playback: Spawns mpv with --input-ipc-server for JSON IPC control over a Unix socket. All playback commands (pause, seek, next/prev) are sent through this socket.
• Data Fetching: Calls yt-dlp directly with -J --flat-playlist --cookies-from-browser <browser> to fetch structured JSON from video platforms.
• Authentication: Reads cookies from your browser's local storage via yt-dlp's --cookies-from-browser flag. No OAuth setup required — if you're logged into a platform in your browser, it just works.
• Auto-Refill: A background monitor watches playlist position and fetches more content when running low, appending via mpv's loadfile append IPC command.

Platform Support

Feature	YouTube	TikTok
Play single video	Yes	Yes
User profile feed	Yes	Yes
Account feeds	Yes (subs, liked, history)	No
Search	Yes	No
Shorts	Yes	N/A
Queue management	Yes	Yes
Audio-only	Yes	Yes
Smart recommendations	Yes	Yes

Example Usage

> Play my subscription feed
> Search YouTube for "rust programming tutorials" and play the first result
> Show me the latest TikToks from @nba
> Play TikTok videos from @khaby.lame
> Queue this video without stopping what's playing: <url>
> Play similar videos to what's on now
> Just play the audio, I don't need video
> Switch to Firefox for cookies
> What chapters does this video have? Then skip to chapter 3

License

MIT