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
mpvwith--input-ipc-serverfor JSON IPC control over a Unix socket. All playback commands (pause, seek, next/prev) are sent through this socket. - Data Fetching: Calls
yt-dlpdirectly 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-browserflag. 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 appendIPC 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
