ClipSeek MCP reference

This page is for developers and advanced MCP clients. For everyday use, start with Connect Codex or Common workflows.

Connection and results

Use the URL shown in Settings → AI Agent:

http://127.0.0.1:<port>/mcp
Authorization: Bearer <token>

The transport is Streamable HTTP. Successful tool data is in structuredContent. Business failures are marked as tool errors and contain { "code", "message" }; authentication failure returns HTTP 401 before the tool runs.

Most tools accept an optional libraryId. Omit it or pass null to use the desktop app's current library. An explicit ID accesses that library without switching the desktop view. list_libraries and get_operation do not take libraryId.

Identifiers, units, and result fields

Field	Meaning
libraryId	Stable library identifier.
assetId	Numeric ID local to a library, returned in asset summaries; useful for restricting a search to one asset's frames.
assetUid, frameUid	Stable UUIDs for assets and frames. Use assetUid in tools that request an asset.
folderId, tagId	Integer IDs local to one library.
operationId	Identifier for an import, image variant, or video clip job.
importedAt, createdAt, dateFrom, dateTo, expiresAt	Unix seconds.
timestampMs, durationMs, startMs, endMs	Milliseconds.
File sizes / aspect ratios	Bytes / width divided by height.

Requests and structured results use camelCase. Asset summaries include the filename, kind, MIME type, size, dimensions, duration, folder, tags, preview URI, and download availability. Visual search also returns the score, matched frame UID, timestamp, and frame preview URI. get_asset adds the import stage, color, and frame list. Raw database and source-file paths are not exposed.

Tool overview

All searches and asset reads exclude Trash. Enabling Agent access permits media reads, original downloads, and temporary derivatives. The four organization/import tools require the extra permission.

Tool	Purpose	Required input
list_libraries	List registered libraries and isCurrent.	None
get_library_context	Get the library, folders, tags, and active counts.	None
search_assets	Search visual content or metadata.	None
get_asset	Get asset details and preview references.	assetUid
get_video_subtitles	Read an imported subtitle track with timestamps.	assetUid
search_subtitles	Search indexed subtitle text.	query
get_operation	Get background job status and results.	operationId
create_asset_download	Issue a temporary original-file download.	assetUid
create_image_variant	Create a resized/cropped image.	assetUid, at least one dimension
create_video_clip	Create an H.264/AAC MP4 clip.	assetUid, startMs, endMs
create_folder	Create a logical folder. Extra permission.	name
update_asset_tags	Add/remove tags. Extra permission.	assetUid
move_assets_to_folder	Change folder assignments. Extra permission.	assetUids
import_assets	Import local files/directories. Extra permission.	paths

Search assets

A nonempty semanticQuery searches visual meaning. Omit it to list/filter metadata. filenameContains performs a case-insensitive filename match in either mode.

{
  "semanticQuery": "rainy neon street",
  "filters": { "kinds": ["video"], "minWidth": 1920 },
  "page": 1,
  "pageSize": 20
}

Results contain items, total, page, pageSize, and hasMore. page defaults to 1; pageSize defaults to 20 and is clamped to 1–50. Visual results sort by relevance and may contain multiple frame hits from the same video. Visual search requires the local model; metadata queries do not.

All search filters and matching rules

Filter	Meaning
assetId	Restrict to one library-local numeric asset ID, including its searchable frames.
folderId	One folder; takes precedence over folderIds and uncategorized.
folderIds, uncategorized	Match any selected folder, optionally including unassigned assets.
tags	Must contain all listed tags.
kinds	Any of image, video, gif.
colors	Any selected color bucket.
minWidth, minHeight	Minimum pixel dimensions.
minAspect, maxAspect	Inclusive width/height ratio bounds.
minSize, maxSize	Inclusive byte-size bounds.
dateFrom, dateTo	Inclusive import-date bounds in Unix seconds.
visualIndexed, subtitleIndexed	Filter by whether the corresponding index exists. Omit for no restriction.
sort	imported_desc (default), imported_asc, name_asc, name_desc, size_desc. Metadata mode only.

Color buckets: red, orange, yellow, green, cyan, blue, purple, magenta, brown, black, white, gray.

Values inside the folder, kind, or color group use OR; different filter groups are combined. assetId also restricts visual retrieval before frame matching. Searches do not expose Trash or a failed-import-only mode.

Read and search subtitles

These tools use subtitles already imported into ClipSeek. They do not transcribe audio, scan neighboring subtitle files, or build search indexes. Setup is described in Subtitle search.

get_video_subtitles — read a subtitle track

{
  "assetUid": "video-uuid",
  "page": 1,
  "pageSize": 50
}

Optional fields: libraryId, version. page starts at 1 and defaults to 1; pageSize is 1–50, default 50. A subtitle search index is not required.

The result contains assetUid, subtitle metadata (version, sourceName, encoding, warnings), cues (startMs, endMs, text), total, page, pageSize, and hasMore.

For later pages, pass the first response's subtitle.version unchanged as version. If subtitles were replaced or removed, subtitle_changed means restart at page 1. Treat the version as an opaque value.

No imported subtitles is a successful empty result: subtitle: null, cues: [], total: 0. A page beyond the end also has empty cues. Non-video input returns invalid_argument; missing or trashed assets return asset_not_found.

search_subtitles — find dialogue

{
  "query": "welcome home",
  "mode": "phrase",
  "porter": false,
  "filters": { "tags": ["selected"] },
  "pageSize": 20
}

Parameter	Behavior
libraryId	Optional target library.
assetUid	Optional video UID; takes precedence over filters.assetId. Omit to search the library.
query	1–200 characters, including at least one letter or number.
mode	keyword (default), phrase, or contains.
porter	English stemming in keyword mode; default false. This does not translate the query.
filters	The metadata filters described above; only untrashed, subtitle-indexed videos can match.
pageSize	1–50, default 20.
cursor	On later requests, pass the previous nextCursor.

Each items entry has an asset summary, subtitle version, startMs, endMs, and matching cues. Cue highlights use UTF-16 offsets, with an inclusive start and exclusive end.

The response also includes hasMore, nextCursor, scanned, and partial. partial: true means the scan budget was reached; if hasMore is true, continue with the cursor even if the page is not full. Keep the query, mode, stemming option, and filters unchanged during pagination. Clear the cursor whenever conditions change.

A video with readable subtitles but no subtitle search index will not match.

Organize and import

These tools return write_disabled unless Allow organization and imports is on. ClipSeek does not show per-call confirmation dialogs; client approval is separate.

Parameters, examples, and import limits

Create a folder

{ "name": "Campaign 2026" }

create_folder creates a logical folder and returns folder. The trimmed name must be nonempty, cannot contain / or :, and cannot start with .. It creates no disk directory.

Update tags

{ "assetUid": "asset-uuid", "add": ["minimal", "blue"], "remove": ["draft"] }

update_asset_tags returns assetUid and the complete updated tags. add and remove default to empty arrays. Names must be nonempty and cannot contain commas. Missing added tags are created. Each call updates tags atomically.

Change folder assignments

{ "assetUids": ["asset-uuid-1", "asset-uuid-2"], "folderId": 8 }

move_assets_to_folder accepts 1–100 UIDs and returns moved. Null or omitted folderId means Uncategorized. Any invalid, missing, or trashed asset rejects the call. Source files are not moved.

Import local media

{ "paths": ["/absolute/path/reference.jpg", "/absolute/path/campaign"], "folderId": 8 }

import_assets accepts 1–100 absolute paths on the ClipSeek computer, scans directories to depth 16 without following symlinks, and queues supported media for copying into the library. folderId is optional; omitted/null means Uncategorized. Invalid paths and unsupported files are ignored; no accepted files returns invalid_argument.

Supported extensions: jpg, jpeg, png, webp, bmp, svg, heic, heif, gif, mp4, mov, webm, mkv, avi, m4v. Format decoding still depends on the media and platform.

Before queueing, ClipSeek checks license quota, free disk space, and conflicting jobs. Duplicates are skipped by content hash. Only one import job runs at a time. The immediate { "operationId", "queued" } result is not completion; poll get_operation for the final counts.

Downloads and generated media

These tools do not need organization/import permission and do not modify originals. Original and generated-file download responses contain downloadId, url, fileName, mimeType, size, and expiresAt.

Original downloads, image variants, and video clip options

create_asset_download

Required: assetUid. Optional: libraryId, fileName. A custom filename affects only the download response and cannot contain a path or control characters.

Downloads normally expire after 10 minutes. Disabling MCP or rotating the token revokes existing grants. The URL contains its own credential, distinct from the MCP bearer token; keep the whole URL private. GET/HEAD and single Range requests are supported; multiple ranges return HTTP 416.

create_image_variant

{
  "assetUid": "image-uuid",
  "width": 1200,
  "height": 630,
  "fit": "cover",
  "format": "webp",
  "quality": 85,
  "background": "#ffffff"
}

Only still images are accepted. At least one of width/height is required; each is 1–8192. One dimension preserves the source ratio. With both dimensions, contain (default) pads with the background; cover center-crops. Formats are jpeg, png, webp; omission preserves these source formats where possible, otherwise outputs WebP. quality is 1–100 (default 85) for JPEG encoding. The background is #RRGGBB, default white. EXIF orientation is applied; source metadata is not copied.

create_video_clip

{
  "assetUid": "video-uuid",
  "startMs": 12500,
  "endMs": 18000,
  "maxWidth": 1920,
  "quality": "balanced"
}

Only videos are accepted, excluding GIFs. Require 0 <= startMs < endMs <= durationMs. Optional maxWidth is 320–3840; scaling preserves the ratio without upscaling. quality is compact, balanced (default), or high. Output is MP4 with H.264 and AAC audio when present. Subtitle burn-in and subtitle-file export are not parameters of this tool.

Both derivative tools also accept libraryId and return operationId; the completed operation's result contains the download information.

Background jobs

Poll get_operation with { "operationId": "operation-uuid" } until status is completed or failed.

• Status is queued, running, completed, or failed; progress is 0–1.
• kind is import, image_variant, or video_clip; stage describes the current phase.
• For imports, inspect total, done, failed, and duplicates. A failed task may still have imported some files successfully.
• result contains the final counts or download information; error provides a failure code and message.
• Jobs are tracked only within the current ClipSeek process. After restart or cleanup, an old ID returns invalid_argument.

Preview resources

Resource templates and size limits

Discover with resources/templates/list; read with resources/read:

clipseek://libraries/{libraryId}/assets/{assetUid}/preview
clipseek://libraries/{libraryId}/frames/{frameUid}

Use the URIs returned in asset results and frame lists. Results contain a Base64 image blob up to 20 MiB, in JPEG, PNG, GIF, or WebP. Only registered library image paths are resolved; invalid IDs, path traversal, and symlink escapes are rejected. These resources do not return original videos. Resource errors include the business code in their error data.

Common errors

Code	What to do
library_not_open, library_not_found	Open a library or choose an ID from list_libraries.
asset_not_found	Refresh the results; the asset may be missing or in Trash.
invalid_argument	Check IDs, parameters, limits, cursors, or operation lifetime.
subtitle_changed	Restart subtitle reading from the first page.
write_disabled, mcp_disabled	Check the service and organization/import switches.
quota_exceeded, quota_usage_unavailable, disk_space_insufficient	Check available quota, registered libraries, and disk space before retrying import.
operation_busy, too_many_operations	Wait for the conflicting job or a derivative slot.
asset_type_unsupported, invalid_time_range	Check asset type and source duration.
derivative_failed	Inspect the message, source media, and free disk space.
download_expired, download_not_found	Request a new download link.
rate_limited	Reduce request frequency and retry later.

Other runtime codes can include library_upgrade_required, unauthorized, db, io, json, library_state, and generic. Use the returned message for context; model loading failures also require checking the local model setup. For recovery steps, see Settings and troubleshooting and MCP security.