Claude Code
How to let Claude Code watch a video
Run `claude mcp add --transport http playhead https://mcp.tryplayhead.com/mcp`, then `/mcp` to sign in. Claude Code can then watch any URL or any file on the machine by path.
One command
claude mcp add --transport http playhead https://mcp.tryplayhead.com/mcpNo deeplink exists for the terminal, so this is the install.
Free tier: 60 credits a month, no card. One credit is about a minute of video.
What this changes
Claude Code has a filesystem, and that changes what this is for. Pass `~/Movies/cut.mov` or `./export.mp4` straight to watch_video: the file is uploaded once and reused for every later call, so your own edits, screen recordings and renders are analysable without publishing them anywhere. That is the loop that matters — render, ask, adjust — and it is the one a browser-only agent cannot close.
Setting it up
- 01
Add the server
claude mcp add --transport http playhead https://mcp.tryplayhead.com/mcp
- 02
Sign in
Run /mcp inside Claude Code and pick playhead. It opens a browser once, and the connection persists.
- 03
Point it at a file or a link
Either works. A path on this machine is uploaded once; a URL is fetched and cached so the second question about the same video is cheaper.
Things worth asking it
Each of these produces an answer with a second attached, because the timestamp is burned into the frame the model is looking at — it cannot lose track of when something happened.
- Watch ./out/render.mp4 and tell me if the logo animation drops frames.
- Compare the pacing of ~/Movies/cut-a.mov and ~/Movies/cut-b.mov.
- At detail=motion, look at 4.2s to 4.8s of this export — is the easing linear?
- Read every line of on-screen text in this screen recording, with timestamps.
How closely it looks is a choice
Six levels, picked by the agent from the question. Surveying an hour and reading a single frame of animation are different jobs, and charging the same for both would make one of them pointless.
| Level | Rate | Answers |
|---|---|---|
| overview | 0.5–2 fps | What is this video, start to end |
| standard | 5 fps | What happens when — cuts, overlays, entrances |
| detail | 5 fps | Objects and text blocks, tiles four times larger |
| fine | 10 fps | Type, logos, subtle transitions |
| motion | 30 fps | Animation, easing, dropped frames |
| single | one frame | Reading text at full resolution |
Questions
- Do I need ffmpeg or yt-dlp installed?
- No. Both run on our machines, not yours. That is the difference between this and a local skill: nothing to install, nothing to keep updated, and it works the same on a Mac, a Linux box and a CI runner.
- Can it look at frames 33 milliseconds apart?
- Yes — detail='motion' extracts at 30 fps, so two consecutive frames land on one sheet a single frame apart. That is the level that answers why a transition feels wrong, and it is billed per second rather than per minute because it extracts six times the frames.
- Does it work in a headless environment or CI?
- Yes, using an API key instead of the OAuth flow. Set PLAYHEAD_API_KEY and the stdio server runs anywhere Node does.
Or somewhere else
One account, every client. The connection is attached to you rather than to a machine, so adding a second one costs nothing.
- ClaudeWeb, desktop and mobile. Opens the connector dialog with the URL filled in.
- ChatGPTNeeds Developer mode under Settings → Connectors → Advanced first.
- CursorAdds the server to Cursor's MCP settings.
- VS CodeOpens VS Code and adds the server to your MCP configuration.
CodexAdd the server to Codex's config file.
[mcp_servers.playhead] url = "https://mcp.tryplayhead.com/mcp" auth = "oauth"Append to ~/.codex/config.toml — the CLI, IDE extension and desktop app share it.
- LM StudioAdds the server to LM Studio's MCP list.