@clipy/mcp

Give your AI agent access to your Clipy screen recordings.

Developed in the Clipy monorepo. A public mirror for browsing the source and filing issues lives at github.com/manovagyanik1/clipy-mcp (MIT), kept in sync with each npm release.

This is a Model Context Protocol (MCP) server. It lets Claude, Cursor, Windsurf, and other MCP-capable agents search your recordings and read their transcripts and AI summaries — so you can do things like "turn this bug-report recording into a Linear ticket" without leaving your agent — and, with the record tool, record a web app headlessly and get it back as a Clipy recording ("build the feature, then record the outcome").

The read tools need the recordings:read scope, which every key gets by default. The write tools — record, the session tools (start_recording, add_marker, add_chapter, stop_recording, abort_recording), and replace_transcript — additionally need the key to carry the ingest scope ("Record & upload"), which the server enforces. A recordings:read-only key can read your recordings but cannot create, modify, or delete anything.

Setup

This is a headless server process, so it authenticates with a Clipy API key in the CLIPY_API_KEY env var (it looks like clipy_sk_live_…). The easiest way to get one is the Clipy CLI's browser login:

npx @clipy/cli@latest login

It opens your browser; click Approve once. The key is saved to ~/.config/clipy/config.json — copy its apiKey value into CLIPY_API_KEY when you add the server below.

Prefer to mint one by hand? Create a key at https://clipy.online/settings/api-keys instead (it's shown only once — copy it immediately).

Then add the server to your MCP client.

Never inline your key into the server's launch command — e.g. "command": "sh", "args": ["-c", "CLIPY_API_KEY=… npx -y @clipy/mcp"]. Command-line arguments are visible to every local process via the process table (ps, /proc), so a key placed there is effectively world-readable on the machine. Always put it in the env block, exactly as every example below does. (The one-time claude mcp add --env … / codex mcp add --env … helpers below write that env block for you — they expose the key only in the argv of that single setup command, never in the long-running server's.)

Claude Code

The --scope user flag installs Clipy globally for every project. Without it, claude mcp add defaults to local scope (the current folder only):

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

Codex

This writes the server to your global ~/.codex/config.toml, so it's available in every Codex session:

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

Or add it to ~/.codex/config.toml by hand:

[mcp_servers.clipy]
command = "npx"
args = ["-y", "@clipy/mcp"]
env = { CLIPY_API_KEY = "clipy_sk_live_xxx" }

Claude Desktop / Cursor / Windsurf

Edit the matching user-level config (claude_desktop_config.json, ~/.cursor/mcp.json, or the Windsurf MCP config) directly:

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

Tools

Read tools accept a recording's public id (the slug in its share URL) or the full https://clipy.online/video/<id> URL.

Capturing the real screen is CLI-only. These tools record a headless Chromium page. To record the actual Mac screen or a specific window (ScreenCaptureKit — the real logged-in browser), use the Clipy CLI: clipy record --source mac-screen --window "<app>".

Using record

record opens a URL in a headless Chromium (works in CI / cloud sandboxes, no display), records for a few seconds, and streams it into Clipy — then returns the id so you can call wait_for_artifacts and get_agent_context to read it back. It needs:

1. Playwright in the environment running this MCP server:
   hljs language-bash

   Copy

   npm install -g playwright && npx playwright install chromium
   

2. An API key with the "Record & upload" (ingest) permission — choose it when you mint the key at clipy.online/settings/api-keys.

Parameters: url (required, http/https), durationSeconds (default 15, max 300, applied per viewport pass), name, description, type (recording kind — bug_report, feature_request, product_demo, walkthrough_tutorial, feedback_review, discussion_talk, other, plus aliases), viewports (e.g. mobile,desktop or 390x844,1440x900 — recorded sequentially into one video, frame sized to the largest, each pass slow-scrolled and auto-chaptered), storageState / initScript (paths, never logged), notes, and width/height (default 1280×720, ignored when viewports is set).

Recording behind a login. storageState seeds exactly what its JSON contains (cookies + localStorage) but can't reproduce a whole browser identity (IndexedDB, service workers, some cross-origin auth). For a full identity, pass userDataDir — Chrome's user-data root (macOS: ~/Library/Application Support/Google/Chrome) — in one of two modes:

• Copy a named profile (recommended). Add profileDirectory ("Profile 1", "Default", … — the exact folder from chrome://version → Profile Path). Clipy copies that profile into a temporary root and records the copy, so your real profile is never opened or modified and the copy is deleted after upload. The tool result discloses the copy (profile name, bytes, and a warning if Chrome was running while it was copied).

  ⚠️ macOS: cookie logins may not survive the copy. Chrome encrypts cookies with the Chrome Safe Storage Keychain key; the recorder's bundled Chromium looks for Chromium Safe Storage. So on macOS a copied profile can produce a browser that looks like your identity but is silently logged out wherever the session is cookie-based — localStorage/ Preferences-based sessions still work. This is a pre-existing Playwright-vs-Chrome constraint, not something the copy introduces, and the copy disclosure repeats it. If the recording lands logged out, that's why. Record the real browser with the CLI's clipy record --source mac-screen, or drive your own browser and attach evidence via add_marker's observed/verdict.

• Open the Default profile directly. Omit profileDirectory. Clipy opens the root's Default profile and writes to it, so it's refused while a live Chrome holds it locked — quit Chrome first. When the dir looks like a real Chrome root, the result carries a userDataDirWarning saying so and pointing you at profileDirectory (ephemeral copy) or the CLI's --source mac-screen instead. Prefer those unless you specifically want in-place use.

Playwright strips Chromium's --profile-directory (it always loads Default from whatever dir it's given), so copying is the only way to record a named profile. Pointing userDataDir at a profile subdir (.../Chrome/Default) is refused — launching from there would silently record a blank, logged-out profile.

storageState and userDataDir are mutually exclusive; profileDirectory requires userDataDir.

Check the camera before you work

record and start_recording both return a source object describing what is actually being recorded, resolved fresh at start time — the post-redirect url, the page title, and the recording viewport:

"source": {
  "kind": "headless_browser",
  "title": "Orders — Admin",
  "url": "https://app.example.com/orders",
  "viewport": { "width": 1280, "height": 720 }
}

Compare it against the surface your driver is acting on before doing minutes of work. This exists because driver-attested evidence proves what the driver observed and nothing ties it to what the camera saw — it's entirely possible to produce truthful marks over footage of the wrong thing. Clipy will never focus or foreground a window or tab for you; pointing the driver and the camera at the same surface is the caller's job.

kind is always headless_browser here: these tools record a headless page Clipy owns. Capturing a real application window or display is CLI-only (clipy record --source mac-screen --window "<app>"), so no window id or window title is reported — an empty or invented one would be exactly the kind of false confidence this field exists to prevent.

Evidence on a marker: two provenances

add_marker can carry evidence in exactly one of two provenances — they are tallied and rendered separately, never pooled:

Use driver-attested when your agent drives its own browser/tooling while Clipy records (e.g. --source mac-screen on the CLI) or when there's no Clipy-owned page to assert against. It's weaker than clipy-verified but far stronger than plain prose. The transcript's leading [verification] note segments the two, e.g. [verification] 3 clipy-verified: 2 passed, 1 failed · 2 driver-attested: 2 passed, 0 failed.

Driving the recorded page over CDP (start_recording + exposeCdp: true)

Pass exposeCdp: true to start_recording and the recording browser opens a Chrome DevTools Protocol endpoint; the result returns cdpHttpUrl + cdpUrl. Connect your own Playwright and drive the page while Clipy records it:

const { chromium } = require("playwright");
const browser = await chromium.connectOverCDP(cdpHttpUrl);
const page = browser.contexts()[0].pages()[0]; // the page being recorded
await page.goto("http://localhost:3000/settings");
await browser.close();                          // detaches; the recording keeps going

It's off by default — while it's open, any local process can attach to that browser. CLIPY_DISABLE_CDP=1 is a hard kill switch that forces it off. Gotchas: the recorded page is contexts()[0].pages()[0] (a new context you open won't be captured); page.viewportSize() reads null over a CDP attach; and to change the viewport use newCDPSession + Emulation.setDeviceMetricsOverride, not setViewportSize.

In-page bridge (zero extra tool calls). When exposeCdp is on, the recorded page also exposes window.__clipyMark(text, opts?) and window.__clipyChapter(label), so your CDP driver can drop asserted marks/chapters from inside the page:

await page.evaluate(() =>
  window.__clipyMark("saved the form", { assertSelector: ".toast", assertText: "Saved" }),
);
await page.evaluate(() => window.__clipyChapter("AFTER — fix applied"));

opts mirrors add_marker (assertSelector / assertText / assertUrl / failMode); assertText requires assertSelector (the call rejects otherwise), and a failed assert with failMode: "abort" discards the session — same annotations and tally as the tools.

Config

Privacy

Your key only ever reads your own recordings. Revoke it any time at /settings/api-keys. The server runs locally on your machine; your key is never sent anywhere except to the Clipy API over HTTPS.