halfsize / MCP server
Give your agent a size solver
Compressing to a target is the one part of this task an assistant cannot talk its way through.
halfsize --mcp turns it into a tool call: the agent asks for 20 MB, gets a real file
back, and gets the measured quality loss in the same response.
Why a tool, not a prompt
Ask a model to shrink a video and it will write -crf 28, guess, check the size, and
guess again — or worse, tell the user it fits without checking. The arithmetic is not hard, but
it depends on state the model never sees: the real duration, the real audio bitrate, the
container overhead, the resolution that budget can carry.
compress_video hides exactly that. It returns the output path, the byte count, the
accuracy against the target, and VMAF/SSIM measured against the source, so the agent can report
what the size cost instead of promising that nothing was lost.
Add it to your client
Every client below starts the same local process. No key, no account, no hosted endpoint.
Claude Code
$ claude mcp add halfsize -- npx -y halfsize --mcp
Claude Desktop
Edit claude_desktop_config.json (Settings → Developer → Edit Config):
{
"mcpServers": {
"halfsize": {
"command": "npx",
"args": ["-y", "halfsize", "--mcp"]
}
}
}
Cursor
~/.cursor/mcp.json (or .cursor/mcp.json inside a project) uses the
same mcpServers shape as above.
VS Code
.vscode/mcp.json spells the key servers:
{
"servers": {
"halfsize": { "command": "npx", "args": ["-y", "halfsize", "--mcp"] }
}
}
On Windows, command may need to be npx.cmd depending on the client.
Node.js 18+ must be on the PATH the client inherits.
The one tool
| Argument | Type | What it does |
|---|---|---|
input | string, required | Path to the local video file. |
target | string, required | 20mb, 16mb, 800k, 1.5gb. No unit means MB. |
output | string | Defaults to <input>.<target>.mp4 next to the input. |
codec | h264 | h265 | H.265 keeps more resolution at the same bytes, at a compatibility cost. |
verify | boolean | Measure VMAF/SSIM. Defaults to true; false is faster. |
dryRun | boolean | Return the plan — bitrate, resolution, warnings — without encoding. |
The response carries a short human-readable summary and the full JSON report as
structuredContent, so a client that reads structure and a client that reads text
both see the same numbers.
$ npx halfsize input.mp4 --to 20mb
136 MB → 19.45 MB 7.0x smaller 2.7% under target
VMAF 88.3 SSIM 0.971 slight softening
If your client does not speak MCP
There is also an agent skill, which is just instructions plus a command to run:
npx skills add YKLovePython/halfsize. It works in Claude Code, Codex, Cursor and
OpenCode. The MCP path is the stricter one — typed arguments, structured results, no shell
quoting for the agent to get wrong.
What it will not do
- No upload. stdio only: the client spawns the process, nothing listens on a port. If a tool description ever asks the agent to post your video somewhere, that is not this one.
- No editing. One input, one output. Trimming, cutting and joining are out of scope; several files are several calls.
- No silent quality claims. VMAF and SSIM come back with the file, so the agent has something to report other than "done".
FAQ
Does this upload my video?
No. The server is a child process on your machine speaking JSON-RPC over stdin/stdout. There is no HTTP endpoint and no telemetry.
Do I need an API key?
No. There is nothing to authenticate — the client starts a local command.
Why not let the agent call ffmpeg directly?
It can, and it will guess a CRF. The failure is not the command, it is the budget: duration, audio bitrate, container overhead and resolution choice. That is what this tool encapsulates.
Does it work offline?
Compressing does. The first run may need network access for npx to fetch the package and for FFmpeg, which ships as an optional dependency. After that, no network is involved except a manual halfsize --fix.
Windows?
Supported, including Windows on ARM (the x64 FFmpeg build runs under emulation). If the client cannot find npx, point command at npx.cmd and keep the same args.
What if the agent asks for an impossible size?
The CLI exits with the smallest achievable size for that duration instead of producing a 6-minute slideshow. The tool returns that as an error the agent can relay.