Clipps CLI + MCP

clippsapp exposes your Clipps library over a CLI and an MCP stdio server, so any AI client (Claude Desktop, Claude Code, Cursor, Windsurf, a Custom GPT Action) can read and save to your own videos, notes, brains, and lists.

All requests are scoped to the signed-in user. Firestore security rules enforce request.auth.uid == userId on every read and write, so a paired API key physically cannot reach anyone else's data.

Install

npm i -g clippsapp

This installs two binaries:

• clipps: the CLI
• clipps-mcp: the MCP stdio server (for AI clients)

Requires Node 20 or newer.

Pair this machine

clipps login

A browser opens at app.clippsapp.com?cli_login=true&port=.... Sign in, and the web app POSTs a fresh API key back to a local callback on 127.0.0.1. The CLI writes the key to ~/.config/clipps/auth.json with chmod 0600.

If your environment has no browser, or the web app has not shipped the CLI callback yet:

clipps login --manual

Paste a key generated from Clipps > Settings > Developer > API keys. The CLI validates the key against /api/auth/whoami before storing it.

To unpair:

clipps logout

CLI commands

clipps login                            # browser pairing (--manual to paste a key)
clipps logout                           # remove ~/.config/clipps/auth.json
clipps whoami                           # show the paired account

clipps save <url> [--note "text"]       # save a URL to your library
clipps search <query> [--limit N]       # full-text search
clipps recent [--limit N]               # most recent saves
clipps list                             # alias for `clipps recent`

clipps brain chat <brain> "<question>"  # ask a curated Brain
clipps brain export <brain> [--out f.md] [--format markdown|json|system-prompt]

clipps list export <list> [--out f.json] [--format json|markdown]

Every read command accepts --json for machine-readable output.

Brains and lists can be referenced by id or by case-insensitive name. Ambiguous names error out so you can pass the exact id.

MCP setup

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "clipps": {
      "command": "clipps-mcp"
    }
  }
}

Restart Claude Desktop. You should see the clipps tools appear in the model's tool list.

Cursor

Settings > MCP > Add new server:

Name: clipps
Command: clipps-mcp

Windsurf

Plugins > MCP Servers:

{
  "clipps": {
    "command": "clipps-mcp"
  }
}

Claude Code

The skill markdown at skills/clipps.md is already shaped for Claude Code. Drop the clippsapp install and:

{
  "mcpServers": {
    "clipps": { "command": "clipps-mcp" }
  }
}

in your ~/.claude/settings.json (or per-project equivalent) to activate the tools.

MCP tools exposed

• clipps_search({ query, limit? })
• clipps_read({ videoId })
• clipps_recent({ limit? })
• clipps_save({ url, note? })
• clipps_brain_chat({ brainIdOrName, question })
• clipps_brain_export({ brainIdOrName, format? })
• clipps_list_export({ listIdOrName })

Every tool result that includes a saved video carries videoId and sourceUrl so downstream agents can link straight back to the original post.

ChatGPT Custom GPT Actions

A ready-to-import spec lives at openapi.yaml. In ChatGPT:

1. Configure > Create a GPT > Configure > Actions > Import spec.
2. Paste the contents of openapi.yaml, or host it somewhere ChatGPT can fetch.
3. Auth > API Key > Custom header, with header name X-API-Key. Paste a key generated from Clipps > Settings > Developer.

The GPT now has searchVideos, listRecentVideos, saveUrl, brainQuery, listBrains, exportBrain, listMyLists, and exportList actions, all scoped to the paired account.

Environment overrides

• CLIPPS_API_BASE: point at a staging or local functions emulator.
• CLIPPS_WEB_BASE: override the web origin used by clipps login (defaults to https://app.clippsapp.com).
• CLIPPS_CONFIG_DIR: store auth.json somewhere other than ~/.config/clipps.

Privacy and security

• Every request carries your per-user API key. Revoke keys any time from Settings > Developer.
• Firestore rules enforce request.auth.uid == userId on every user-owned collection. The app-layer filters in the CLI and MCP server are defense in depth, not the authorization boundary.
• auth.json is written with mode 0600 and contains a hashed-at-rest API key reference, not any other credentials.
• clipps logout removes the local file. Revoke the key in the Clipps web app to invalidate it server-side.

Development

cd packages/clipps-cli
npm install
npm run build
node dist/cli.js whoami     # should say "Not signed in"
node dist/mcp.js < /dev/null  # MCP stdio server is alive when this hangs

The package is part of the Clipps monorepo but is published standalone as clippsapp. No internal packages are bundled or imported.

Changelog

0.1.1, 2026-04-26

• Fix login/auth flow: the default API base URL was missing one /api segment, causing every authenticated request to 404 and clipps login to fail post-callback. Republished with the corrected default. If you ran clipps login on 0.1.0, just upgrade and re-run; no other action needed.