Playback MCP

YouTube control for AI agents.

Loop, seek, sequence clips, and search transcripts in your real browser — driven by Claude Code or any MCP client.
Local-first, free, MIT.

Demo

What you can do with it

How it works

One broker owns the localhost port and routes each session to its own tab. Every playback-mcp server shares a single library on disk.

Run several sessions at once and each drives its own YouTube tab in parallel. The broker auto-starts on first use and idles out ~a minute after the last session closes.

Install

The released way — no clone, no build. Requires Node 24 LTS (≥ 23.4; uses the built-in node:sqlite) and Chrome.

1. Install the server — the playback-mcp package.

   npm i -g playback-mcp
   

2. Add the extension — install Playback MCP from the Chrome Web Store. One click, and it stays up to date automatically. (Running a custom YT_BRIDGE_PORT? The Web Store build bakes in port 8765 — build from source instead.)

3. Register it with your MCP client. Any MCP client works — for Claude Code:

   claude mcp add playback-mcp -- playback-mcp
   

   Or project-scoped (committed, shared with anyone who opens the repo) via a .mcp.json at the repo root:

   { "mcpServers": { "playback-mcp": { "command": "playback-mcp" } } }
   

4. Open a YouTube video and ask — "pause it," "loop the chorus twice at 0.75×," "find where they mention hooks."

Tools

Time inputs are forgiving: "90", "1:30", "1m30s", "1:02:03"; speeds accept "0.75x".

Safe by design

The extension only reads and writes the <video> element's own properties — currentTime, playbackRate, volume, play/pause. It never clicks UI, never scrapes, and never automates navigation beyond opening a watch URL. Everything runs on 127.0.0.1; your library lives in a local SQLite file and nothing is sent to any external server.

Configuration

¹ Linux: ~/.local/share/playback-mcp (respects XDG_DATA_HOME) · macOS: ~/Library/Application Support/playback-mcp · Windows: %APPDATA%\playback-mcp

Build from source

For development, or to run a custom YT_BRIDGE_PORT (the released extension bakes in port 8765 at build time):

pnpm install
pnpm run build

1. Open chrome://extensions, enable Developer mode
2. Click Load unpacked and pick extension/dist
3. Register the server: claude mcp add playback-mcp -- node /abs/path/server/dist/index.js

Troubleshooting

• "Chrome extension is not connected" — make sure the extension is loaded and Chrome is running; it reconnects automatically within a few seconds.
• Tools work but nothing happens on screen — confirm this session's managed YouTube tab still exists; open_video creates one. Each session controls only its own tab.
• Multiple sessions — supported: each runs its own playback-mcp and drives its own tab. They share a background broker daemon (playback-mcp-broker) that starts automatically on first use and shuts down ~a minute after the last session closes.
• "This video has no captions available" / transcript errors — get_transcript and search_transcript fetch captions straight from YouTube for the open video; some videos genuinely have no captions, and lang must match an available track.

Development

pnpm run build
node scripts/mcp-poke.mjs       # full smoke test over real MCP stdio, no browser needed
node scripts/fake-extension.mjs # mock extension that acks all commands (for manual poking)

See CONTRIBUTING.md for the workflow, and SECURITY.md to report a vulnerability.

License

MIT © 2026 Blaise Moses