How to Give Claude (or Cursor) Access to Your Screen Recordings

You recorded a bug. Your AI assistant can't see it. So you describe it in prose, the assistant guesses, and you're back to the same lossy game screen recording was supposed to kill.

The fix is to give the agent the recording directly. Not a YouTube-style "watch this 90-second video" link it can't open — the actual transcript, the AI summary, and (when it needs pixels) the MP4 on disk. That's what the Clipy MCP server does. This is a hands-on walkthrough: the bug-to-ticket workflow first, then setup for each client, then the troubleshooting that saves you the head-scratching.

What this actually lets Claude do

The Model Context Protocol (MCP) is the standard way to plug tools and data into an AI agent. The Clipy MCP server is a small program that runs on your machine and exposes your Clipy recordings as MCP tools. When Claude (or Cursor, or Windsurf) is connected, it can:

• Search and list your recordings by keyword or recency.
• Read a transcript — timestamped segments plus flat plaintext.
• Read the AI summary — TL;DR, key points, and action items Clipy already generated.
• Download the MP4 locally so it can clip a segment or extract frames with its own tools.

Two facts matter before you wire it up, because they shape everything else:

1. It is read-only. The current MCP and API surface can search and read recordings — it cannot create, edit, or delete them. Your key reads only your own recordings. So there's no "oops, the agent deleted my library" failure mode; the worst it can do is read something.
2. It runs locally over stdio. The server is a Node process launched by your MCP client (via npx), talking over standard input/output. There's no extra daemon to babysit and no inbound network port. It needs Node 18 or newer.

The hero workflow: turn a bug recording into a ticket

This is the reason to bother. The shape is simple, and it's the one most teams adopt first.

1. Record the bug. Open Clipy, hit record, reproduce the bug while narrating: what you're on, what you clicked, what you expected, what happened instead. (If you want the discipline behind a tight 30-second repro, we wrote the 30-second bug report playbook.) Stop. The share link is on your clipboard.
2. Hand the link to Claude. In your editor or Claude Desktop, paste something like: "Here's a bug recording: https://clipy.online/video/<id> — read the transcript and summary and draft a GitHub issue with steps to reproduce, expected vs. actual, and environment."
3. Claude reads it. It calls get_summary and get_transcript for that id, pulls the narration and the action items, and writes the ticket — repro steps from your spoken walkthrough, expected/actual from your narration, and a link back to the recording so the engineer can watch the 20 seconds that matter.
4. If it needs the pixels, it downloads the clip. Say the bug is a visual glitch the transcript can't capture. Claude calls download_recording, gets the MP4 on disk, and runs ffmpeg itself to clip the relevant 8 seconds or extract a frame to attach.

You went from "recorded a bug" to "filed a clean ticket" without typing the repro steps yourself, because you already said them out loud while recording.

A clear-eyed note on download_recording

It's worth being precise about what download_recording does, because it's easy to over-claim. Here is the exact mechanic:

• The tool first fetches the recording's metadata through the owner-scoped Clipy API (so it needs your key, and it only works on your recordings).
• From that metadata it gets the CDN URL of the MP4, then downloads the file directly from the CDN to a local path and returns that path. The API does not proxy the video bytes — the download is CDN-to-disk.
• From there, the agent operates on the file locally. Clipy does not clip the video or extract frames server-side through MCP — your agent does that with its own tooling, e.g. ffmpeg -ss 00:00:05 -t 10 -i clip.mp4 out.mp4 to grab a segment, or ffmpeg -i clip.mp4 -vf fps=1 frame_%03d.png to pull frames.

To be fair to the rest of the platform: Clipy does do server-side processing on a normal recording — it transcodes the upload, transcribes it, and generates the AI summary. What it doesn't do is clip-on-demand through the MCP server. That split is the whole design: heavy, repeatable work (transcribe, summarize) happens once on Clipy's side and is served as text; one-off, agent-specific work (clip this 8 seconds, pull that frame) happens on your machine where the agent already has ffmpeg. Keeping that line straight saves you from expecting a server-side trim endpoint that isn't there.

Step 1: create an API key

Go to clipy.online/settings/api-keys and create a key. A few things to know:

• It looks like clipy_sk_live_xxx.
• It's shown only once — copy it the moment it appears. If you lose it, revoke it and mint a new one.
• It's revocable any time, and it reads only your own recordings. Treat it like a password: don't commit it to a repo, and prefer your client's env-var config over pasting it into shared files.

Step 2: install the server for your client

The server is the npm package @clipy/mcp. You don't install it globally — your MCP client runs it on demand with npx -y @clipy/mcp, so it's always the published version. Pick your client below.

Claude Code / Claude Desktop

One command. Run it in your terminal (swap in your real key):

claude mcp add clipy --env CLIPY_API_KEY=clipy_sk_live_xxx -- npx -y @clipy/mcp

That registers a server named clipy, sets your key as an environment variable, and tells Claude to launch it via npx. Restart the client (or start a new session) and the seven tools show up.

Cursor

Cursor reads MCP config from ~/.cursor/mcp.json (or a project-level .cursor/mcp.json). Add a clipy entry under mcpServers:

{
  "mcpServers": {
    "clipy": {
      "command": "npx",
      "args": ["-y", "@clipy/mcp"],
      "env": { "CLIPY_API_KEY": "clipy_sk_live_xxx" }
    }
  }
}

Save, then reload Cursor. The same JSON block works for Claude Desktop (in its claude_desktop_config.json) and for Windsurf's MCP config — the shape is identical across MCP clients; only the file location differs.

Windsurf and other MCP clients

Any MCP-compatible client that supports stdio servers can run this. Drop the same mcpServers → clipy block into that client's MCP config file. If your client lets you set an environment variable for the server, put CLIPY_API_KEY there instead of inline — it's cleaner and keeps the key out of the JSON you might share.

The seven tools, and when the agent reaches for each

You rarely call these by hand — the agent picks them. But knowing what's available helps you write better prompts ("summarize the last three recordings about checkout" maps cleanly onto list_recordings + get_summary).

• search_recordings — find recordings by keyword (matches title + description), with an optional status filter. The agent uses this when you reference a recording by topic rather than link.
• list_recordings — most recent recordings, newest first. For "my latest recording" style prompts.
• get_recording — one recording's metadata: title, description, duration, and the status of its transcript and summary.
• get_transcript — the full transcript: timestamped segments plus flattened plaintext. The workhorse for bug-to-ticket.
• get_summary — the AI summary: TL;DR, key points, action items. Often enough on its own.
• wait_for_artifacts — polls until the transcript (and optionally the summary) finish processing, then returns them. This is the one that matters right after a fresh recording (see troubleshooting).
• download_recording — pulls the MP4 to a local path so the agent can clip or extract frames with ffmpeg.

Every id-taking tool accepts either the bare public id (the slug in the share URL) or the full https://clipy.online/video/<id> URL, so you can paste whichever you have on your clipboard.

Worked example: from recording to issue

Here's a realistic exchange so you can see the tool calls in context. You've just recorded a checkout bug and pasted the link:

You: Here's a bug recording: https://clipy.online/video/a1b2c3d4e5f6 — read it and draft a GitHub issue. If the visual matters, attach a frame.

What the agent does, in order:

1. Calls get_summary("a1b2c3d4e5f6") → gets the TL;DR and action items.
2. Calls get_transcript("a1b2c3d4e5f6") → gets your narrated repro steps with timestamps.
3. Writes the issue: a one-line summary, numbered repro steps lifted from your narration, expected vs. actual, environment (you said "Chrome 132, signed in as Pro" out loud), and a link to the recording.
4. Because you asked for the visual, it calls download_recording("a1b2c3d4e5f6"), gets the MP4 path, then runs ffmpeg -ss 00:00:12 -i clip.mp4 -frames:v 1 frame.png against the timestamp where the transcript says the glitch appeared, and attaches the frame.

You read the draft, tweak one line, and file it. The repro steps wrote themselves because you spoke them while recording — the agent just transcribed your intent into the issue template.

Beyond bug tickets: other workflows this unlocks

Bug-to-ticket is the gateway drug, but the same read-only plumbing answers a lot of "I recorded that, where did it go?" questions. A few that work today, each just a prompt away:

• Recorded standups and syncs. "Pull the action items from my standup recording from this morning" — the agent runs list_recordings, finds it, reads get_summary, and hands you the decisions and owners without you rewatching ten minutes of video.
• Product demos into release notes. If you walked through a new feature on camera, the transcript already contains the script. Ask the agent to turn the last demo recording into draft release notes or a changelog entry.
• Onboarding and SOPs. You recorded yourself doing a task once. "Read that recording and write the step-by-step doc" turns the narration into a written runbook your teammates can skim.
• Searching across recordings. "Find the recording where I explained the auth flow" maps onto search_recordings, and the agent reads the matching transcript instead of making you scrub through thumbnails.

The common thread: you already did the talking. The transcript and summary are sitting there. MCP is just the wire that lets your agent reach them, so the recording becomes input instead of an archived file you have to open and watch.

Why text-first, and not just screen-sharing the video

You might wonder why this isn't simpler — why not just point a vision model at the video frame by frame? Two reasons it's text-first by default. First, cost and latency: feeding a transcript and a summary into an agent is cheap and fast; streaming a multi-minute video through a vision model is neither. Clipy already paid that cost once — it transcribed and summarized the recording on upload — so reading text is reusing work that's already done. Second, precision: a transcript with timestamps lets the agent jump to the exact moment that matters and, only then, download and clip just those few seconds. That's why download_recording exists as a separate, opt-in step rather than the default — pixels are pulled when the words aren't enough, not before.

Troubleshooting: the gotchas that actually bite

"The transcript isn't ready yet"

This is the most common one, and it's not a bug. When you record something brand new, Clipy still has to transcode, transcribe, and summarize it — that takes a little time after you stop. If the agent calls get_transcript in that window, it gets a status (like queued or processing), not the text.

The fix is built in: tell the agent to use wait_for_artifacts, which polls until the transcript (and optionally the summary) reaches a terminal state, then returns it. A prompt like "wait for the transcript to finish, then draft the ticket" nudges it down that path. If it times out, it returns a resumable status — just have it call again.

"No such recording" or empty results

Your key is owner-scoped: it only sees recordings that belong to you. If you paste a teammate's share link, the API legitimately returns nothing, because that recording isn't yours. This is the privacy boundary working as designed, not a config error.

The server won't start

• Node version. The package requires Node 18+. Check with node -v; if you're on 16, upgrade.
• Missing key. If CLIPY_API_KEY isn't set, the server exits immediately with a message pointing you to the settings page. Double-check the env block in your client config — a stray quote or a key pasted into args instead of env is the usual culprit.
• Tools don't appear. Restart the client after editing config; most MCP clients only read the config on launch.

download_recording says "no downloadable video yet"

If a recording is still processing, its MP4 may not be on the CDN yet. get_recording shows you the status; once it's ready, the download succeeds. Same root cause as the transcript timing — give a fresh recording a moment.

Where this fits, and where it's going

The honest framing: today the integration is read-and-operate. The agent reads your recordings' text, and when it needs pixels it downloads and works on them locally. That's deliberately a narrow, safe surface — read-only by design, so connecting Clipy to an agent can't damage your library.

It's also genuinely useful right now. If you already record bugs, demos, or async standups, you've been sitting on a pile of transcripts your AI tools couldn't reach. MCP reaches them. The bug-to-ticket loop is the obvious win, but the same plumbing answers "what did we decide in yesterday's recorded sync?" or "pull the action items from my last three product-demo recordings" — all on top of the summaries Clipy already made.

If you're a developer wiring this into a workflow, the developer overview and the MCP docs have the REST surface under the hood (every tool wraps a small read-only /api/v1/recordings endpoint you can hit with any Bearer-capable client). And if you don't record on Clipy yet, the free, no-signup screen recorder is the front door — record once, and every transcript becomes something your agents can read.

The five-minute setup recap

1. Mint a key at clipy.online/settings/api-keys (copy it once).
2. Run claude mcp add clipy --env CLIPY_API_KEY=clipy_sk_live_xxx -- npx -y @clipy/mcp — or paste the mcpServers → clipy block into Cursor/Windsurf.
3. Restart the client.
4. Record a bug with Clipy, paste the link to Claude, and ask it to draft the ticket.

That's the whole thing. Your recordings stop being write-only artifacts your AI tools can't see, and start being a searchable, summarizable corpus your agent reads on demand — read-only, your own recordings, on your machine.