halfsize

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

ArgumentTypeWhat it does
inputstring, requiredPath to the local video file.
targetstring, required20mb, 16mb, 800k, 1.5gb. No unit means MB.
outputstringDefaults to <input>.<target>.mp4 next to the input.
codech264 | h265H.265 keeps more resolution at the same bytes, at a compatibility cost.
verifybooleanMeasure VMAF/SSIM. Defaults to true; false is faster.
dryRunbooleanReturn 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

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.

Related