browser-video-setup

name

browser-video-setup

description

Use when the user has just cloned browser-video-mcp and needs to get it running, or asks how to install / set up / get started / configure the MCP server, or reports that `record_demo` / `capture_auth_state` aren't showing up in `/mcp`. Also use on ffmpeg, Playwright-browser, or `dist/index.js not found` errors. Walks through npm install → playwright install → build → `.mcp.json` trust → smoke test, catching the common gotchas that cause silent tool-registration failures.

browser-video-mcp setup guide

You are helping the user go from a fresh git clone of this repo to a working MCP server that exposes record_demo and capture_auth_state inside their client. The user is running Claude Code in the repo root, so everything is repo-relative — no absolute paths.

The happy path

Do these in order. Run safe commands (npm install, npx playwright install, npm run build) yourself after briefly saying what you're about to do. Confirm before anything that touches system package managers (Homebrew, apt, etc.).

1. Check prerequisites (in parallel)

• node --version — must be ≥ 20. If lower, point the user at nvm / fnm and stop; nothing downstream will work on older Node.
• which ffmpeg (or ffmpeg -version) — needed for MP4 output and the optional GIF post-process. If missing:
  • macOS: brew install ffmpeg
  • Linux: apt install ffmpeg (or distro equivalent)
  • Windows: install from ffmpeg.org and add to PATH
  • If the user only ever wants format: "webm" and no also_gif, ffmpeg is optional — tell them so instead of forcing an install.

2. Install JS dependencies

npm install

3. Install the Playwright browser binary

npx playwright install chromium

npm install pulls the Playwright library but not the browser binaries — this step is what makes chromium actually launchable. Skipping it produces browserType.launch: Executable doesn't exist, which looks like an MCP bug but isn't. Use npx playwright install (no arg) if the user also wants Firefox and WebKit.

4. Build

npm run build

This compiles TypeScript to dist/index.js, which is the entry point .mcp.json points at. Verify dist/index.js exists before moving on — if the build silently produced nothing, any later MCP-not-found errors will be misleading.

5. Register the server

The repo ships a project-scoped .mcp.json at the root:

{ "mcpServers": { "browser-video": { "command": "node", "args": ["./dist/index.js"] } } }

Claude Code auto-discovers this file but does NOT enable it until the user approves it. Tell the user to:

1. Exit and re-open Claude Code in this directory (or run /mcp to refresh).
2. Approve the .mcp.json trust prompt when it appears.
3. Run /mcp to confirm browser-video shows as connected and lists record_demo + capture_auth_state.

If the user is on Claude Desktop instead, .mcp.json is ignored — point them at the "Register with Claude Desktop" section of README.md, which uses an absolute path in claude_desktop_config.json. Offer to print the exact JSON with their absolute dist/index.js path filled in.

If the user wants record_demo available from other projects too (not just inside this clone), suggest a user-scoped install as an alternative:

claude mcp add --scope user browser-video -- node <absolute-path>/dist/index.js

Both can coexist; the project-scoped one just means it works automatically here.

6. Smoke test

Once /mcp shows the server connected, offer to run the minimal demo so you both know the full pipeline (Playwright → recording → ffmpeg → output file) works. Use the no-auth quickstart prompt from the README:

Record a ~10-second demo of https://example.com using record_demo. Caption the intro, highlight the h1, then click the first link. Save to ./demos/smoke.mp4.

If that produces a playable MP4, setup is done. If it fails, the server response includes failed_step_index, partial_video_path, and screenshot_path — those locate the problem precisely.

Common breakages and what they actually mean

Symptom	Real cause	Fix
record_demo missing from /mcp after restart	.mcp.json not trusted, or trust was denied	Re-open Claude Code, accept the trust prompt, re-check /mcp
browserType.launch: Executable doesn't exist	Skipped step 3	npx playwright install chromium
ffmpeg not found even after brew install ffmpeg	PATH inherited by Claude Code was cached before install	Fully quit and relaunch Claude Code so it picks up the new PATH
Cannot find module '.../dist/index.js'	Skipped step 4, or the build failed	Run npm run build and read the TypeScript errors
Build succeeds but dist/index.js is empty/truncated	Partial write from a killed tsc	rm -rf dist && npm run build
A recording run produces a .failure.png and partial video	Setup is fine — the user's selector or timing is wrong	That's a script authoring problem, not a setup problem. Don't try to "fix" the install.

What to avoid

• Don't suggest claude mcp add --scope local or --scope user as the primary path when the repo already has a working .mcp.json. It adds a duplicate entry that confuses later debugging.
• Don't edit dist/ by hand; it's generated.
• Don't commit ./.auth/ or ./.secrets/ — record_demo's capture_auth_state writes session cookies there. .gitignore already excludes both, but verify before pushing if the user added files under a new path.

When setup is "done"

All four are true:

1. node --version ≥ 20, ffmpeg resolves (unless WebM-only is OK for the user).
2. dist/index.js exists and is non-trivial in size.
3. /mcp in Claude Code lists browser-video as connected with both tools.
4. The smoke test produced a playable ./demos/smoke.mp4.

Only then should you hand off to the normal demo-authoring workflow documented in README.md.