clipquery

Search a personal video library with natural language. Videos processed by the Flashback system are split into ~30-second segments, analysed for visual content, transcribed, and embedded; a query is matched semantically against those segments, and each result comes back with an AI-generated description, a relevance score (0–1), a direct URL to view the segment, and the time that URL expires. Presigned URLs expire after 1 hour — run the query again for fresh ones.

Configuration

Two environment variables are required for query_videos:

• FLASHBACK_USER_ID — your unique Flashback account identifier (e.g. 4087fce3-3d86-4047-b35f-4004b4c19192)

• FLASHBACK_API_BASE_URL — the base URL of the Flashback video processing API. The upstream publishes no default, so this must be set; a missing value is an error naming the variable, raised before any request.

get_setup_instructions is local and needs no configuration.

Related MCP server: Video Query MCP Server

CLI

npx @reneturcios/clipquery query "person talking" --max-results 5
npx @reneturcios/clipquery query "meeting discussion about deadlines"
npx @reneturcios/clipquery setup
npx @reneturcios/clipquery --version

Exit codes: 0 on success, 1 on a runtime error (including missing configuration), 2 on a usage error.

MCP server

npx -y @reneturcios/clipquery mcp

MCP client config:

{
  "mcpServers": {
    "clipquery": {
      "command": "npx",
      "args": ["-y", "@reneturcios/clipquery", "mcp"],
      "env": {
        "FLASHBACK_USER_ID": "your-flashback-user-id",
        "FLASHBACK_API_BASE_URL": "https://your-flashback-api-host"
      }
    }
  }
}

Tools

• query_videos — Search for video clips based on natural language query. query (string, required) — natural language description of what you're looking for; max_results (integer, optional, default 10) — maximum number of results to return (1–15).

• get_setup_instructions — Get detailed setup instructions for the video query system. No parameters.

The server also mirrors the upstream's documented resource URI concept in its guide text only; no MCP resources are served.

Docker

docker run -i -e FLASHBACK_USER_ID -e FLASHBACK_API_BASE_URL ghcr.io/cloudcorprecords/clipquery
docker run --rm ghcr.io/cloudcorprecords/clipquery setup

Development

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (fake fetch only, no network)
npm run dev     # run the CLI from source

License

MIT — Copyright (c) 2026 Rene Turcios