HEVC Transcodelocal quality-gated encode

Let an AI Assistant Manage Your Queue (MCP Integration)

Last updated 2026-10-25 · Hoelee Enterprise · 638, Jalan Raja Muda, Aulong, 34000 Taiping, Perak, Malaysia · me@hoelee.com

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.

What the assistant can do

ToolWhat it answersExample you can type
get_status_summaryA 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_itemsWhy: 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_activityThe 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_lanesStart 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_operationRun 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_actionA 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_actionExecutes 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.

What it can not do (by design)

Set it up (2 minutes)

  1. Make sure HEVC Transcode is running. The console listens on 127.0.0.1:8790 — local only, unless you turned LAN access on yourself.
  2. Add the server to your assistant. The easy way: open Settings → AI assistant (MCP) → Copy configuration. It puts a ready-to-paste JSON block on your clipboard with the correct path for your installation.

    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: Settings → Developer → Edit Config → paste into claude_desktop_config.json → restart Claude.
    • Cursor: Settings → MCP → Add new MCP server → paste the same block.
    • Anything else: any client that speaks MCP over stdio works — this is a plain stdio process.
  3. Ask it something. Try "What is the transcode queue doing?" If it answers with real numbers, you are done.

Good questions to ask

If something looks wrong

SymptomWhat it meansWhat to do
ERR_SUPERVISOR_DOWNThe console is not running, or it is on a different portStart HEVC Transcode and ask again
The tools do not appear in the assistantThe client was not restarted after the config editRestart the assistant
An answer says reused: trueThe same scan or self-test is already running; the server attached to that job instead of scanning twiceNothing — wait for it to finish (the answer says how long it has been running)
ERR_CONFIRM_MISMATCHA file landed in the queue between the preview and the actionAsk for the preview again; the token is bound to the exact item set
ERR_LICENSE_REQUIREDThe licence agreement has not been accepted yetAccept it in the app window — an assistant cannot do this for you

Error codes

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.

All 17 error codes (click to open)
CodeMeaning
ERR_ANSWER_TOO_LONGThe answer would not fit the size budget, so it was cut (see `truncated`).
ERR_ARG_INVALIDAn argument has a value the tool does not accept.
ERR_ARG_MISSINGA required argument is missing (for example `file_id` with `scope=file`).
ERR_CLASS_NOT_BATCHABLEThat category cannot be handled as a batch at all.
ERR_CONFIRM_EXPIREDThe confirmation token is older than 5 minutes - preview again.
ERR_CONFIRM_MISMATCHThe category, action, count or item set changed since the preview (a file landed in the meantime) - preview again.
ERR_CONFIRM_MISSINGThe call came without a `confirm_token`.
ERR_CONFIRM_REQUIREDThe action needs a confirmation token: preview it first.
ERR_CONFIRM_USEDThat token was already used. Tokens are single-use by design.
ERR_HTTPThe console answered, but not with the expected JSON (a proxy page, a refusal, or the background-job limit).
ERR_LICENSE_REQUIREDThe 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_FOUNDThat lane, queue row or tool does not exist.
ERR_SUPERVISOR_DOWNThe console is not reachable on 127.0.0.1:8790.
ERR_TIMEOUTThe console did not answer in time (it is busy with a scan or a preview).
ERR_UNMAPPEDThe console refused for a reason without a dedicated code; the message carries it.
ERR_UNSUPPORTED_ACTIONThat action is not allowed for this lane or this decision category.
ERR_UNSUPPORTED_OPThat background job kind is not one of scan / report / doctor.

Privacy — please read this one

  1. Nothing leaves unless you ask. It reads state only when you send a question; there is no background upload.
  2. Your video is never uploaded. What goes to the AI provider (Claude, Cursor, …) is text only: queue progress, quality scores, file names. Not one byte of your video files leaves this machine.
  3. You can switch it off whenever you like. Remove the entry from your client's config — or point the client at a local model (Ollama and similar) if even file names must stay on your network.

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