Clipy MCP — Setup & Reference

The Clipy MCP server gives an AI agent read-only access to your screen recordings' transcripts and AI summaries. It runs locally over stdio and talks to the Clipy API with your personal key. For the why and the use cases, see the MCP overview.

1. Create an API key

Go to clipy.online/settings/api-keys and create a key. It looks like clipy_sk_live_… and is shown only once — copy it immediately. The key reads only your own recordings and can be revoked any time.

2. Install the server

Claude Code. The --scope user flag installs Clipy globally for every project. Drop it and claude mcp add falls back to its default local scope — the current folder only, which is why the server "disappears" in your other repos.

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

Prefer to edit config by hand? Paste the block into the matching user-level file — claude_desktop_config.json, ~/.cursor/mcp.json, or the Windsurf MCP config:

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

…or, for Codex, into ~/.codex/config.toml:

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

3. Tools

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

tool	args	does
search_recordings	query, status?, limit?	Search recordings by keyword.
list_recordings	status?, limit?	List recent recordings.
get_recording	id	Metadata + processing status.
get_transcript	id	Full transcript (segments + plaintext).
get_summary	id	AI summary (TL;DR / key points / action items).
wait_for_artifacts	id, require?, timeoutSeconds?	Poll until transcript/summary are ready.
download_recording	id, outputPath?	Download the MP4 locally to clip / extract frames yourself.

4. REST API (under the hood)

The server wraps a small read-only REST surface. You can call it directly with any Bearer-capable client:

curl -s https://clipy.online/api/v1/recordings \
  -H "Authorization: Bearer clipy_sk_live_xxx"

method	path	returns
GET	/api/v1/recordings?q=&status=&limit=&page=	List / search your recordings.
GET	/api/v1/recordings/{id}	One recording's metadata + statuses.
GET	/api/v1/recordings/{id}/transcript	Timestamped segments + plaintext.
GET	/api/v1/recordings/{id}/summary	TL;DR, key points, action items.

All endpoints are owner-scoped: a key only ever returns the recordings that belong to its owner. Transcript/summary endpoints return status (e.g. queued, ready) so you can poll while a fresh recording finishes processing.

Config

CLIPY_API_KEY (required) — your key.
CLIPY_API_URL (optional) — base URL, defaults to https://clipy.online.

Back to the MCP overview · package on npm: @clipy/mcp