# Playback Mcp > Control YouTube playback from local AI agents and MCP-compatible tools like Claude Code, Codex, etc. - **Type:** MCP server - **Install:** `agentstack add mcp-blaisemoses01-playback-mcp` - **Verified:** Yes โ€” security-reviewed for prompt injection and unsafe behavior - **Seller:** [BlaiseMoses01](https://agentstack.voostack.com/s/blaisemoses01) - **Installs:** 0 - **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [BlaiseMoses01](https://github.com/BlaiseMoses01) - **Source:** https://github.com/BlaiseMoses01/playback-mcp - **Website:** https://blaisemoses01.github.io/playback-mcp/ ## Install ```sh agentstack add mcp-blaisemoses01-playback-mcp ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About 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 | | | | ------------------------ | ------------------------------------------------------------------------------- | | ๐ŸŽธ **Music practice** | Loop a passage and ramp the speed up pass by pass, hands-free. | | ๐Ÿ—ฃ๏ธ **Language learning** | Slow a sentence down and jump to every place a phrase is spoken. | | ๐Ÿ“ **Study & notes** | Summarize a lecture from its transcript and save timestamps to revisit. | | ๐Ÿณ **Cooking & how-tos** | Turn a recipe or tutorial into written steps โ€” or a clip reel of the key parts. | | โœ‚๏ธ **Shorts & clips** | Mine a long video for short-form ideas and pull the exact clips. | | โญ๏ธ **Skip the filler** | Find the sponsor reads in a long podcast and jump past them. | ## 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. Full multi-session architecture Each session gets a unique `sessionId`. The broker tags commands with it, multiplexes every server onto the one extension connection, and routes events back only to the owning session. Saved videos and timestamps live in a single WAL-mode SQLite database (`node:sqlite`) shared across all servers. A WebSocket Origin allow-list at the handshake means only the extension and local Node clients can connect โ€” arbitrary web pages can't drive playback. ## 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`](https://www.npmjs.com/package/playback-mcp) package. ```sh npm i -g playback-mcp ``` 2. **Add the extension** โ€” install [Playback MCP from the Chrome Web Store](https://chromewebstore.google.com/detail/playback-mcp/nggfclklnclpmoclihggncjhccbecbed). 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](#build-from-source) instead.) 3. **Register it with your MCP client.** Any MCP client works โ€” for Claude Code: ```sh 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: ```json { "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 | Tool | What it does | | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `play` / `pause` | Resume (optionally from a time/label) or pause | | `seek` | Jump to a time (`"1:30"`, `"90"`, `"1m30s"`) or a saved timestamp label | | `set_speed` | 0.25ร—โ€“2ร— playback rate | | `set_volume` | Absolute 0โ€“100 or relative `"+10"`/`"-10"` | | `loop_section` | Loop a section N times, optionally with per-pass speeds (e.g. 0.5 โ†’ 0.75 โ†’ 1.0). Returns immediately; the loop runs in the browser | | `stop_loop` | Cancel the active loop | | `play_sequence` | Play a list of clips back-to-back, skipping the gaps between them. Returns immediately; runs in the browser | | `stop_sequence` | Cancel the active clip sequence | | `save_video` / `find_videos` / `open_video` | Build and search a library of saved videos; open them in a managed tab | | `save_timestamp` / `list_timestamps` / `delete_timestamp` | Named positions and loopable sections per video | | `get_transcript` | Caption transcript of the open video as `[m:ss] text` lines; optional `start`/`end` window and `lang` | | `search_transcript` | Find a word/phrase in the transcript; returns timestamps with context โ€” pair with `seek` to jump to a topic | | `get_state` | Full player state; works even when the extension is disconnected | 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 `` 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 | Env var | Default | What | | ----------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `YT_BRIDGE_PORT` | `8765` | WebSocket port between server and extension. The extension bundle captures this at build time, so if you change it you must rebuild the extension with the same env var set. | | `PLAYBACK_MCP_DATA_DIR` | platform data dirยน | Where the SQLite library lives (`library.db`) | ยน 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): ```sh 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 ```sh 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](CONTRIBUTING.md) for the workflow, and [SECURITY.md](SECURITY.md) to report a vulnerability. ## License [MIT](LICENSE) ยฉ 2026 Blaise Moses ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source โ€” we do not rehost the code. - **Author:** [BlaiseMoses01](https://github.com/BlaiseMoses01) - **Source:** [BlaiseMoses01/playback-mcp](https://github.com/BlaiseMoses01/playback-mcp) - **License:** MIT - **Homepage:** https://blaisemoses01.github.io/playback-mcp/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** โ€” Free ## Security capabilities Automated source analysis of v0.1.0 โ€” what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source โ€” more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** โ€” security scan: passed โ€” Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-blaisemoses01-playback-mcp - Seller: https://agentstack.voostack.com/s/blaisemoses01 - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack โ€” the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.