---
id: automation-mcp
title: Local MCP assistant
summary: Connect an assistant, inspect and edit projects, explicitly translate, voice, retranscribe or export, track jobs, and understand costs, file access and consent.
platforms: [windows, macos]
app_version: "1.39.0"
review_basis: source-review
reviewed: "2026-10-05"
error_codes: [externalAiConsentRequired, modelNotInstalled, apiKeyMissing, apiKeyInvalid, invalidInput]
labels: [MCP, automation, translation jobs]
aliases: [Claude Code, Claude Desktop, Cursor, VS Code, stdio, MCP prompts, requestKey, get_frame, edit_segments, project_history, prepare_translation, translate_video, retranslate_segments, revoice_segments, retranscribe_project, export_project, cancel_job, connect assistant, AI helper, edit my video, stop translation, assistant cannot connect]
canonical: https://aivideotranslator.app/docs/automation-mcp.html
order: 10
---

# Local MCP assistant

This help describes AI Video Translator 1.39.0. If you are helping someone and do not know which version they use, ask them to open Settings → About App and read App Version (for example `1.39.0+3`; use the part before `+`). Help for another version: https://aivideotranslator.app/docs/<version>/llms-full.txt (replace <version>; the list of published versions is in https://aivideotranslator.app/llms.txt)

You can connect your own AI assistant to search Help, edit your projects and translate videos. The app runs the processing, while your assistant can check how it's going or ask it to stop.

## Connect an assistant

You'll need to turn on assistant access, which starts off. The app gives you setup text for the version you've installed, so you can copy it into your assistant.

1. Open “Settings”.
2. Open the MCP tab.
3. Turn on “Allow AI agents to control the app (MCP)”.
4. Finish any startup dialogs in the app.
5. For Claude Code, choose “Copy for Claude Code”.
6. For Claude Desktop or Cursor, choose “Copy for Claude Desktop or Cursor”.
7. For VS Code, choose “Copy for VS Code”.
8. Add the copied setup to your assistant.
9. Connect from the assistant.

You can see on this tab whether access is off, waiting for an assistant or connected. If you move or update the app, copy the setup again so your assistant has the current location.

Your assistant must run on the same computer as the app to use this local connection. A remote or cloud agent can't connect this way, and some assistants may not be compatible.

You enter provider keys in the app, so you don't need to share them in chat.

If connection fails while the app is closed, open the app manually. Then connect the assistant again.

## What the assistant can see

Once connected, your assistant can inspect every registered project the app can access, even ones you haven't opened. You can't set separate permissions for each project or assistant.

Your assistant can read transcripts, translations, project notes, glossary, terms, settings, speakers, timing and voice status. It can also look at pictures from your source video without changing the project or creating an image file.

To inspect a picture, the app needs access to your source file and a time within the video. It uses a separate silent player, so it doesn't disturb your preview.

Your assistant can search Help and find the available languages, providers, models and voices. It can't read your provider API keys, server addresses or provider configuration.

## What the assistant can change

You can ask your assistant to edit text, timing, speaker assignments and segment structure. It can also change project settings and speakers, or give fast voice lines more room by stretching them into nearby pauses.

If your project is open, you'll see these edits straight away. Free edits don't translate text or make voices, but changing translated text or a speaker can leave a line needing a new voice.

When you change a speaker's speed, it affects every line using that speaker. If you want a different speed for one line, you'll need a separate speaker for it.

You can undo each assistant batch as one shared step, including its timing edits. Your history lasts until you close the app; while you're typing in a text field, undo affects that field's text.

If saving fails partway through a batch, you may still see some changes. Your assistant must check what happened before continuing, and you can use shared history for the changes that were saved.

If you want to replace the source video, you'll need to use the project's form in the app. Your assistant can't give the app file access just by changing a path.

## Translate a video

You tell your assistant which source file to use, which language you want and a separate destination file. It checks your choices before starting and asks you for anything missing.

1. Choose the source file in the app's file browser.
2. Choose the destination folder in the app's folder browser.
3. Install any required models or voices in the app.
4. For cloud providers, configure their keys in the app.
5. For cloud providers, allow external AI services in the app.
6. Ask the assistant to prepare the translation.
7. Review its choices and warnings.
8. Ask it to start.

Typing a path in chat doesn't give the app access to that file or folder. Trusting your assistant doesn't grant that access either; you choose the file or folder in the app.

If something is missing, your assistant may show you a menu or ask in chat. The built-in workflow prompts only give instructions; they don't start work themselves.

## Process an existing project

You can explicitly ask your assistant to translate or voice selected lines, replace a transcript or export a project. Once you ask, that work starts without another confirmation in the app.

If you use cloud providers, they can charge you for this work. You can't undo processing results or exports, and your assistant must never repeat paid work automatically after an error or restart.

When you generate voices, the app keeps recordings that still match your text and settings. Export uses your current voices without translating or making missing ones; if an included segment needs work, that blocks the export.

If a new transcription succeeds, it clears your project history. If work fails or you cancel, results the app already saved can remain.

If you edit a line while processing runs, the app keeps your edit instead of an outdated result. Your assistant gets a warning naming the affected lines, though you may already have paid the provider for that work.

You can run only one processing task at a time. If you've started work in the editor, your assistant's processing request can be blocked until it's done.

## Check progress or stop

Once the app accepts a job, it keeps running even if your assistant stops waiting or disconnects. If you want to stop it, ask your assistant to cancel the job, then check its status.

Your job can be waiting to start, running, stopping, finished, failed, cancelled or interrupted. Even if it fails, your assistant can still tell you its progress, warnings and what went wrong.

If you close the window or quit during processing, you'll see “Processing is running — quit and stop it?”. You can choose “Keep processing” to leave the app running.

If you confirm quitting, the app stops processing. When you reopen it, unfinished jobs are marked interrupted and won't resume automatically.

If you turn assistant access off, the app disconnects assistants and closes the connection. Jobs it has already accepted keep running.

## Find the finished video

You get one saved video at the destination you requested. Your assistant tells you its actual path, size and any warnings.

If your chosen video extension doesn't match the exported format, the filename uses the format's extension. Keep the file at that location if you want to retrieve it from the job again.

When export succeeds, the app marks your project completed, even if you get a free-tier warning. If you've archived the project, it stays archived.

## Understand the free limit

You get the same free allowance through automation as in the app, with no extra Premium requirement. A normal whole-video job can translate and make voices for every line, but your export dubs only the first 10 segments.

Your video keeps its full length. Whole-video assistant jobs replace the original audio without mixing in background sound, so you'll hear silence after the first 10 segments.

If you export an existing project, it uses that project's audio settings. [Export and audio tracks](https://aivideotranslator.app/docs/1.39.0/export-and-audio-tracks.md) explains how you can keep background sound or an original audio track.

You can ask your assistant to require a full dub. If you don't have Premium and the transcript exceeds the allowance, the job stops before translating or making voices, though you may already have paid for transcription.

Requiring a full dub also blocks an existing-project export if it exceeds the allowance. Your assistant must tell you every warning before starting and after finishing; it must never change that requirement or retry automatically.

## Protect your privacy

Your assistant receives content it asks for, including transcript text and pictures from your source video. Its own terms govern how it handles that content and may allow cloud processing.

Choosing on-device translation doesn't mean your assistant keeps its processing local. Your consent for external AI services controls the app's provider requests, but doesn't control what your assistant does with content it receives.

When you export, the reply gives your assistant a file location without sending the video through this connection. If it has separate file access, your assistant can read or share that video.

The app keeps returned frame images out of logs, crash reports and usage statistics. [Terms and Privacy](https://aivideotranslator.app/legal.html#p2) explains the rules that apply to assistants, Shortcuts and Siri.

## Fix a refused request

If a request is refused, your assistant must tell you why and stop before repeating paid processing. If the cause is unexpected, you can look in Help or contact support.

1. If file access is missing, choose the source file or destination folder in the app's browser.
2. If an accessible file is missing, choose an existing file or folder.
3. If a model is missing, install it in the app.
4. If a request value is invalid, correct the value named in the message.
5. If another edit changed the project, ask the assistant to read it again before editing.

Until you've given access, the app can't check whether a file exists. If it reports a request validation error, that doesn't mean an AI provider rejected your video.

## Technical details

If you're a developer or connecting an AI agent, these details describe the interface. You can inspect `tools/list` for the schemas and capabilities in your installed build.

### Connection and prompts

You connect through the installed executable with `--mcp`, which runs as a local stdio server. On Mac, the usual path is `/Applications/AI Video Translator.app/Contents/MacOS/AI Video Translator`. On packaged Windows, use the enabled `videotranslator.exe` alias; on unpackaged Windows, use the actual `ai_video_translator.exe` path.

For Claude Code, the copied setup uses `claude mcp add --transport stdio --scope user ai-video-translator`. For Claude Desktop/Cursor, the copied JSON uses `mcpServers`; for VS Code, it uses `servers`. Both JSON setups include `type: stdio`, the actual executable and `args: ["--mcp"]`.

If access is disabled, `initialize` returns JSON-RPC `-32000` with `data.code: mcpDisabled` and no tools or prompts. The proxy can still launch the GUI, but disabling access removes the endpoint descriptor and listening socket.

At initialization, your host receives workflow instructions. It can get the `translate_video`, `edit_project` and `troubleshoot_job` prompts through `prompts/list`; these don't run tools themselves. The host decides how to present them, and you don't need to install a repo skill.

For the translation prompt, provide string `video_path` and `target_language`, and optionally `source_language`. For editing, provide `project_id` and optionally `goal`; for troubleshooting, provide `job_id`.

If you omit the source language, preparation uses detection if the model supports it. If prompt arguments are invalid, the reply returns `-32602` and names the argument, or `arguments` for unknown fields. It never echoes your request (`request: null`).

### Replies and project reads

Tool replies use `{status, summary, revision?, data, warnings, error?, next}`. You'll also find legacy catalog, plan and job fields at the top level.

1. Relay every localized warning message.
2. Follow `next` without automatic paid retries.

You can filter `list_projects` by name with `query` and page with `limit` 1–100 (default 50) and `cursor`. Use `get_project` to read settings and speakers, or `list_segments` to read rows ordered by start time then ID. These reads don't select or migrate projects.

With segment `fields`, you can select `id`, `window`, `speakerName`, `sourceText`, `targetText`, `configuredVoice`, `voicing` and `timing`. You can combine filters for `ids`, exact `speaker`, `voicingState`, `needsAcceleration` (minimum 1), case-insensitive `textContains` and `timeMs`.

Time filters match start ≤ time < end. For audio status, the app looks up and measures recordings on disk as it does for export, instead of using stored GUI flags. If it can't measure the duration, you get null.

For duration D and window W, required acceleration is max(1, D/W), applied acceleration is capped at 3, and planned end is start + D/applied acceleration. Overrun tells you how much still doesn't fit; synthesis speed is a speaker setting.

Successful reads give you a revision. Each cursor is tied to that revision, fields, filters and order; if you get `revisionConflict`, restart without the cursor and keep your fields and filters.

Text replies have a 65536-byte UTF-8 budget, including structured data, JSON text and framing. Pages keep items whole instead of truncating them; if you get `responseTooLarge`, you may need fewer fields. You can't page project details.

### Free edits

For `edit_segments`, `edit_project` and `even_out_acceleration`, provide `projectId`, the latest `expectedRevision` and a stable `requestKey`. Use a new key for each new batch. Only when recovering a lost reply, reuse the original key and identical input, including its old revision.

With `edit_segments`, you can use `set_text`, `assign_speaker`, `retime`, `move`, `add`, `delete` and `merge`, with speakers that already exist. Ripple moves include following rows; merges need adjacent rows and keep the first ID and speaker. Adds need a gap and allocate max(id)+1.

You can submit up to 100 operations and affect up to 200 rows/writes; the app checks the reply budget before writing. If you send unknown fields, conflicting writes, missing rows or invalid timing, it rejects the whole batch before writing anything.

Your receipt includes `historyEntryId`, `applied`, `notApplied`, `uncertain`, `createdIds`, `deletedIds` and `invalidatedAudioIds`. The app leaves deleted IDs out of invalidation and the next-read selection.

Validation tells you the zero-based `operationIndex`, the field or rule and any numeric limits, including the 1000 ms shrinking minimum.

If the operation index is null, the refusal applies to the batch; messages never copy submitted text, and `projectNotFound` has no revision. The app saves rows individually, so a failure can leave some changes saved. In that case, you get `partial`, and those changes share one undo entry.

With `edit_project`, you can change whitelisted settings and add, update, rename or remove speakers. Names refer to the original table, so you can swap or chain names in one batch. You can't remove speakers that lines still use.

With `even_out_acceleration`, the app checks recorded durations even for projects you haven't opened. Unselected rows still act as boundaries, and a preview doesn't write anything.

1. Preview with `preview: true`.
2. Apply the same IDs with a new request key.

You can use `project_history` for `list`, `undo`, `redo` and `rollTo`, with a listing cursor and limit 1–100 (default 50). To replay history, provide the latest revision. For `rollTo`, also provide `entryId`; that entry stays applied.

If you get `revisionConflict`, read the project again; `editBusy` means a human edit holds a conflicting lease. Reads, previews, rejected calls and no-ops don't add history entries. Accepted free-edit receipts and undo history stay available while the app runs, even across host connections.

### Processing and recovery

For `prepare_translation`, provide `videoPath`, `outputPath`, language codes and any optional provider, model or voice choices. If choices are missing, you get `needs_input`; a host with forms can collect the enumerated choices.

Preparation gives you a `planId` for that connection, which you start with `translate_video(planId, requestKey)`. The optional boolean `requireFullDub` starts as false and belongs to the plan, rather than the start call.

If you don't have Premium, a ready plan includes a localized `freeTierLimit` advisory, but preparation still succeeds. Default exports warn with `freeTierLimited`; if a required full dub is refused, that code becomes an error instead.

For `retranslate_segments` and `revoice_segments`, provide the project ID, revision, key and exactly one selection branch: `ids`, `all: true` or `missing: true`. The app expands all or missing once when it accepts the job. Missing means empty translations, or translated rows that need synthesis.

For `retranscribe_project`, provide the project ID, revision and key. For `export_project`, also provide `outputPath` and optionally `requireFullDub`; if export is blocked, `exportBlocked` lists `blockedSegmentIds` within the export allowance.

When the app accepts work, you get `status: accepted` and `data: {jobId, operation, projectId, acceptedRevision}`. Jobs use durable request identities and share one paid-run lease, so a GUI run can cause a `busy` reply.

If you change input while reusing an accepted key, you get `requestConflict`. An accepted job keeps its request identity even if it fails or is interrupted.

1. After a lost reply, reuse the key and normalized inputs.
2. After reconnecting, prepare the same whole-video choices again with the original key.

If a model is missing, you get `modelNotInstalled` without a dialog. Each provider request checks consent again, and provider-internal retries follow editor policy. If the app discards outdated results, `staleResultsDiscarded` names the affected `segmentIds`.

With `get_job_status(jobId, waitMs)`, you can wait 0–55000 ms. During that wait, progress strictly increases and only appears while a call with a progress token is active. To stop processing, use `cancel_job`; it cancels the job rather than the wait.

You'll see states `accepted`, `running`, `cancelling`, `succeeded`, `failed`, `cancelled` or `interrupted`. Reads of failed or interrupted jobs still give you a full snapshot marked as an error, with a nested localized code/message. If the read itself fails, there's no job state, and the reply keeps the legacy top-level code/message.

Job warnings only accept code/message and optional integer `segmentIds`; job errors only contain code/message. If an unexpected exception occurs, you get `internalError`, while explicit provider error codes keep their identity.

If you get `invalidInput`, it names the argument to correct. Paths without a grant return `pathAccessRequired` before the app checks existence; if it has access but the source is missing, you get `videoNotFound`.

Export results give you the actual path, MIME type, size and warnings, without video bytes. After success, the job advises you to verify surviving rows with `list_segments`; after failure, it points you to Help or the troubleshooting prompt.

### Frame inspection

For `get_frame`, provide `{projectId, timeMs, maxWidth?, maxHeight?}`, with no path or decoder fields. Use a nonnegative integer time within the measured source duration; if it's invalid, the error names `timeMs`.

The reply gives you JPEG image content and `{projectId, requestedTimeMs, width, height, mimeType, bytes}` in the envelope data. Bytes means the encoded size; requested time tells you what was requested, not a measured frame timestamp.

Your frames keep the source's display aspect and orientation. The default maximum edge is 1280 pixels, within caps of 1920 × 1080; any positive bounds you request are capped at those limits too.

Images have a 2 MiB budget, with one retry at a smaller size and lower quality. Requests run one at a time with a 30-second deadline. If you cancel or disconnect, the app disposes the muted decoder before releasing source access.

Inspecting a frame doesn't create a file, bookmark, picker, provider request, revision change or history entry. If access is missing or revoked, you get `pathAccessRequired`; `next` suggests `list_segments` with `filter.timeMs`.