Let Claude, Cursor or any MCP-capable assistant read your transcode queue — and control it, safely.
HEVC Transcode ships with a local MCP server. It runs on your own machine, talks only to the console that is
already running on 127.0.0.1:8790, and never touches your video files directly.
Everything it can do, you could do by clicking — it just saves you the clicking.
| Tool | What it answers | Example you can type |
|---|---|---|
get_status_summary | A compact snapshot: each lane's state, how many items are queued and how long that will take, what today saved, how many items need a decision (by category), infrastructure failures, disk / licence / backend guards, recent events and who started them. | "What is the queue doing right now?" |
explain_items | Why: the items in a folder that will be processed next, the items waiting for your decision (why each was refused, which gears were tried, the SSIM it reached), or the full attempt history of one file - backend, device, gear, command, failures. | "Why were 327 files in this folder skipped?" |
get_recent_activity | The latest runs and events, newest first. Each event says who started it: the owner at the console, an AI assistant, or the app itself. | "Did anything fail while I was away?" |
control_lanes | Start a lane, let it finish the current file and then stop, or stop right now. The default is "finish the current file"; "stop now" throws away the progress of the file being encoded and has to be asked for explicitly. | "Finish the current file on the GPU lane, then stop." |
trigger_operation | Run a folder scan, the backend self-test, or export the quality/space report. It returns an operation id immediately; asking again while it runs attaches to the same job (`reused: true`) instead of scanning the disk twice. | "Scan for new videos." |
preview_decision_action | A dry run for the items that need a decision: how many items this category covers, how much source data that is, which actions the category allows - plus a one-time confirmation token (5 minutes). Nothing is changed. | "What would happen if I accepted those 12 items?" |
apply_decision_action | Executes an action that was previewed. It needs the token from the preview; if the category, the action, the count or the set of items changed in the meantime the server refuses and asks for a new preview. The assistant is told to ask you first. | "Yes, accept them." |
Every write goes into the event log with the actor marked ai-agent, so
"what did the assistant do last night?" is a question the console can answer.
127.0.0.1:8790
— local only, unless you turned LAN access on yourself.Typing it by hand looks like this:
{
"mcpServers": {
"hevc-transcode": {
"command": "C:\\Users\\\\AppData\\Local\\Programs\\HEVC-Transcode\\python\\pythonw.exe",
"args": ["-m", "rt.mcp_server", "serve"]
}
}
}
claude_desktop_config.json → restart Claude.| Symptom | What it means | What to do |
|---|---|---|
ERR_SUPERVISOR_DOWN | The console is not running, or it is on a different port | Start HEVC Transcode and ask again |
| The tools do not appear in the assistant | The client was not restarted after the config edit | Restart the assistant |
An answer says reused: true | The same scan or self-test is already running; the server attached to that job instead of scanning twice | Nothing — wait for it to finish (the answer says how long it has been running) |
ERR_CONFIRM_MISMATCH | A file landed in the queue between the preview and the action | Ask for the preview again; the token is bound to the exact item set |
ERR_LICENSE_REQUIRED | The licence agreement has not been accepted yet | Accept it in the app window — an assistant cannot do this for you |
An assistant that gets one of these is expected to explain it and stop, not to retry blindly. They are listed here so a support conversation can quote the exact string.
| Code | Meaning |
|---|---|
ERR_ANSWER_TOO_LONG | The answer would not fit the size budget, so it was cut (see `truncated`). |
ERR_ARG_INVALID | An argument has a value the tool does not accept. |
ERR_ARG_MISSING | A required argument is missing (for example `file_id` with `scope=file`). |
ERR_CLASS_NOT_BATCHABLE | That category cannot be handled as a batch at all. |
ERR_CONFIRM_EXPIRED | The confirmation token is older than 5 minutes - preview again. |
ERR_CONFIRM_MISMATCH | The category, action, count or item set changed since the preview (a file landed in the meantime) - preview again. |
ERR_CONFIRM_MISSING | The call came without a `confirm_token`. |
ERR_CONFIRM_REQUIRED | The action needs a confirmation token: preview it first. |
ERR_CONFIRM_USED | That token was already used. Tokens are single-use by design. |
ERR_HTTP | The console answered, but not with the expected JSON (a proxy page, a refusal, or the background-job limit). |
ERR_LICENSE_REQUIRED | The licence agreement has not been accepted, or the licence does not allow this. Only the owner can accept it, in the app window - an assistant cannot. |
ERR_NOT_FOUND | That lane, queue row or tool does not exist. |
ERR_SUPERVISOR_DOWN | The console is not reachable on 127.0.0.1:8790. |
ERR_TIMEOUT | The console did not answer in time (it is busy with a scan or a preview). |
ERR_UNMAPPED | The console refused for a reason without a dedicated code; the message carries it. |
ERR_UNSUPPORTED_ACTION | That action is not allowed for this lane or this decision category. |
ERR_UNSUPPORTED_OP | That background job kind is not one of scan / report / doctor. |
HEVC Transcode itself sends no telemetry.
Requires HEVC Transcode 1.1.0 or newer. The MCP server is a plain stdio process with no extra dependencies — it uses the Python interpreter that already ships inside the app.
← Back to the product page