Caching & CLI

Downloaded videos, extracted frames, audio tracks, and transcripts are all cached together in a persistent per-video directory. Subsequent tool calls that reference the same video reuse cached artifacts instead of re-running ffmpeg, re-downloading, or re-calling audio provider APIs.

Cache Location

The cache is stored in a video-mcp-cache folder inside your system’s temporary directory:

OS	Path
Windows	%TEMP%\video-mcp-cache (e.g. C:\Users\<you>\AppData\Local\Temp\video-mcp-cache)
macOS	$TMPDIR/video-mcp-cache (e.g. /var/folders/xx/yyyy/T/video-mcp-cache)
Linux	/tmp/video-mcp-cache

Cache Settings

Configure via environment variables:

Variable	Description	Default
VIDEO_MCP_CACHE_TTL_MINUTES	Lifetime of cached artifacts. Set 0 to disable.	43200 (30 days)
VIDEO_MCP_CACHE_MAX_ENTRIES	Max cached videos (LRU eviction). Set 0 for unbounded.	100
VIDEO_MCP_CACHE_MAX_MB	Max total disk size (MB) (LRU eviction). Set 0 to disable.	5120 (5 GB)

Automatic Cleanup

The server manages the cache automatically:

1. Startup sweep — Removes entries older than the TTL on every server start.
2. LRU eviction (entry count) — When VIDEO_MCP_CACHE_MAX_ENTRIES is reached, the least-recently-used video and all its artifacts are evicted.
3. LRU eviction (disk size) — When VIDEO_MCP_CACHE_MAX_MB is exceeded, LRU eviction continues until the limit is satisfied.

Cache Management CLI

The vmcp CLI (alias for video-context-mcp) provides built-in cache management commands. These run immediately and do not start the MCP server.

Check cache status

vmcp cache status

Shows cache location, total size, entry count, TTL setting, and a per-entry breakdown.

Print cache path

vmcp cache path

# Jump into the cache directory (macOS/Linux)
cd "$(vmcp cache path)"

Copy cache to a backup location

# Copy to ./video-mcp-cache (default destination)
vmcp cache copy

# Specify a destination
vmcp cache copy --dest=./backup
vmcp cache copy --dest=/tmp/cache-backup

# Windows
vmcp cache copy --dest=C:\Users\alice\cache-backup

# Paths with spaces
vmcp cache copy --dest="C:\Users\alice\My Documents\cache-backup"

Clear expired entries

Removes entries older than the configured TTL:

vmcp cache clear:expired

Note

CLI commands run as a separate process and do not inherit environment variables from your mcp.json. If you use a custom TTL, pass it explicitly:

VIDEO_MCP_CACHE_TTL_MINUTES=10080 vmcp cache clear:expired

Clear all entries

# Prompts for confirmation
vmcp cache clear:all

# Skip confirmation
vmcp cache clear:all --yes