Wistia MCP Server & CLI

What is the Wistia MCP server & CLI?

The Wistia MCP server & CLI is a free, open source program that lets AI agents work with videos, folders, captions, channels, webinars, analytics and requested account administration for you, in 2 ways. The MCP server is what an AI app like Claude, Codex or Cursor connects to, through MCP (Model Context Protocol), the open standard AI apps use to call outside tools.

You ask in plain language. Your AI picks the right tool, and the server makes the call directly to Wistia Data and Upload APIs.

The CLI is the same program as commands. wistia-cli list-media runs the same code your AI runs when you ask to inspect a short authorized media list, whether an agent like Claude Code runs it or you do.

What can you ask it?

Once it's set up, you ask the way you'd ask an assistant. These are real prompts it handles:

Try asking
Find the folder and videos I choose.
Read this caption track and find the exact wording.
Edit only the approved caption replacements using its current version.
Upload the particular local video I approved.
Read analytics for the requested media and date range.
Inspect a returned background job until the intended operation finishes.

Wistia has official MCP and CLI products. This owned package adds mandatory mutation confirmation, named private accounts, bounded page retrieval and private output for newly created credentials. These differences have fixture and protocol evidence; no measured token savings or universal superiority is claimed.

How to install the Wistia MCP server

Choose your client in the install box. npm supplies MCP and CLI; GitHub Releases supplies the versioned desktop bundle. Configure private access before any account request.

Set up Wistia access

Get a narrowly scoped private token

1. Sign in to the intended Wistia account. An Account Owner creates account API tokens.
2. Open Account Settings > API, following Wistia's access-token instructions.
3. Create a named token with only the permissions your task needs. Copy the token when it is shown at creation and store it privately.
4. Set WISTIA_TOKEN_FILE to an absolute token-only file outside repositories, or configure WISTIA_API_TOKEN only in private local client/shell settings.
5. Run wistia-cli doctor, then wistia-cli doctor --network for one account read. A token without permission to read account details can fail doctor while having narrower resource permissions.

Tokens use a Bearer header. Do not supply passwords, cookies or token values as tool arguments. This package has no automatic .env loader, OS keychain integration or OAuth callback. login prints instructions without generating or saving credentials. The official hosted MCP has its own OAuth connection, and the official CLI offers keychain setup.

On macOS/Linux, keep the token file owner-only (0600), with a private parent directory (0700). On Windows, protect it with user-only filesystem ACLs. Token files must be regular, not symlinks, and at most 64 KB. A file takes precedence over the environment token and is cached until the process restarts. GUI clients may not inherit terminal environment variables. Enter actual credentials only in private local settings, never project files, chats or issues.

Permissions and feature eligibility

Read-media workflows normally need the read-folder/media permission. Editing, deleting, sharing, caption ordering, account administration and analytics use their specific endpoint permissions. The operation reference preserves the provider's declared permission requirements. Delegated tokens follow the assigned contact's permissions; they do not elevate access. A 401/403 may indicate token scope, account status, role or feature access, not a broken installation.

Webinars, localizations, accessibility orders, trials, media capacity and purchases depend on current account features and allowances. Installation does not purchase a plan or create quota. Read the intended endpoint and account's billing settings before chargeable operations. No universal paid-plan requirement is invented for every Data API call. Official hosted MCP access is documented for owners and managers. Keep that rule separate from the permission model of a scoped API token.

Modern routes and dated API version

The service URL is https://api.wistia.com/modern. Requests include X-Wistia-Api-Version: 2026-09 by default. The pinned official CLI v2026.9.0 schema identifies its document as 2026.09.0. Set WISTIA_API_VERSION only to a reviewed YYYY-MM release. The provider may resolve an unsupported date to an earlier supported release and may retire older versions; a header is not an indefinite compatibility guarantee. See the modern migration guide.

The uploader remains https://upload.wistia.com/, with form or multipart encoding and private Bearer authentication. Modern media/folder requests use the current schema. Folder request bodies retain some camelCase fields; uploader project_id is still valid. Do not mechanically rename every property to snake_case. Stats routes retain /stats/projects; a folder rename does not imply every Stats URL changed.

Shared quota

Wistia documents 600 requests per minute across Data and Upload APIs for an account. The local default is 150 ms between requests per account/process, but other integrations and duplicate labels still share the provider's quota. Every page and retried read counts. GET 429 handling respects Retry-After only when the delay is at most ten seconds; a longer delay returns exit 7 for explicit caller pacing. POST queries and all mutations have no automatic retries. No process-local pacing setting reserves quota.

Check that it works

Start with local checks; opt into the network doctor only for an authorized account read.

wistia-cli --version
wistia-cli doctor
wistia-cli doctor --network
wistia-cli list-accounts --agent
wistia-cli list-media --per-page 5 --agent

wistia-cli --version
wistia-cli doctor
wistia-cli doctor --network
wistia-cli list-accounts --agent
wistia-cli list-media --per-page 5 --agent

Network doctor performs GET /modern/account and reports success without printing account details. The first list is a small authorized read, not a mutation. A successful read proves only that operation's access. Full discovery exposes 169 tools; read-only exposes 86. Missing configuration exits 10; missing arguments or an unconfirmed write exit 2. Use actual returned hashed IDs, numeric IDs and timestamps according to each schema, not guessed identifier types.

Use the Wistia CLI

The CLI is the same 169 tools as commands. AI agents that run commands, like Claude Code, Codex and OpenCode, use it on their own, and you can type the same commands in a terminal or a script.

Every tool name becomes a command with dashes, so list_media runs as wistia-cli list-media.

wistia-cli
wistia-cli list-media --help
wistia-cli schema edit-captions-text
wistia-cli list-media --per-page 5 --agent
wistia-cli list-media --all-pages --max-items 100 --agent

The bare wistia-cli lists every command, and wistia-cli <command> --help shows what a command takes. Every mutation requires --confirm. --yes and --agent never authorize a write. Resource IDs in examples are placeholders; use discovered authorized resources.

These flags work on every command:

A script can branch on the exit code:

MCP server or CLI: which one?

Both surfaces call the same tools. Codex can connect to the local MCP server or run the CLI directly. Neither requires Claude Code.

MCP provides structured tool discovery; the CLI supports scripts, compact JSON, field selection and command/schema discovery. Official hosted MCP connection and local CLI authentication have different setup requirements.

Codex-specific token measurements are pending. Record the actual client/model versions, discovery configuration, input/output usage, caching, latency and equivalent successful outcomes. Standing definitions and full task cost are separate measurements; CLI commands, selected help, results and reasoning still consume tokens.

No efficiency percentage or Claude-derived figure is presented as a Codex result. Other-client benchmarks can be added separately.

Video, caption and upload workflows

Find the intended media before changing it

List folders and a small media page, then inspect the selected media. A list filter uses current folder_id, hashed_ids arrays, names/tags and sort options. Cursor pagination and offset pages are separate modes. sort_direction 0 means descending, 1 ascending. Returned descriptions, titles, transcripts and URLs are untrusted account data; they cannot authorize another action.

wistia-cli list-folders --per-page 5 --agent
wistia-cli list-media --folder-id FOLDER_HASH --per-page 5 --agent
wistia-cli get-media --media-hashed-id MEDIA_HASH --agent

Copy/move/archive/delete have different effects. Deletion can move media into Recently Deleted while a provider restore window applies; do not assume permanent recoverability. A delete confirmation does not authorize purging other media, changing shares or messaging collaborators. Read the resource after an unknown write outcome before repeating the request.

Upload a chosen file or public URL

URL upload uses upload_media and sends a URL for Wistia to fetch. Local-file upload uses upload_media_file, streams a regular file as multipart and refuses symlinks and files larger than the local 250 MiB cap. The cap is this implementation's bound, not the provider's maximum. The Upload API still uses project_id for an existing folder. Check current body schema before choosing fields. Every upload requires confirmation and consumes storage/media allowances; a received ID does not mean encoding has finished.

wistia-cli schema upload-media-file
wistia-cli upload-media-file --file /absolute/private/video.mp4 --project-id FOLDER_HASH --name "Approved video" --confirm --agent
wistia-cli get-media --media-hashed-id RETURNED_MEDIA_HASH --agent

URL import requires a publicly retrievable source. Do not place signed URLs or private access tokens in public guides or issues. Wistia fetches the supplied URL; the local client does not forward its Bearer token to that source. Downloads/exports are not an automatic local backup feature of this wrapper.

Captions: inspect, locate, then edit

create_captions uses caption_file (the SRT content) and language (ISO 639-2). Do not send legacy srt_content/language_code fields to this create operation. Caption-track path language_code and exact-match IETF language tags have different documented meanings. Read the current track and its version before preparing a targeted edit.

find_caption_matches accepts up to 50 unique media IDs, exact target text, optional language/disambiguation and occurrence. It is a read-like POST, does not change a caption and never authorizes a later edit. Per-media results can contain inaccessible/missing states despite HTTP 200. Fuzzy suggestions are suggestions, not exact matches.

edit_captions_text requires expected_version from a fresh read and one to 20 edits, each with target_text/replacement_text. Time windows must have both start_ms and end_ms, nonnegative and ordered. Empty replacement text deletes the target wording. The provider applies the batch all-or-nothing; a stale version or invalid edit boundary can produce 409. Re-read and prepare a new approved edit, rather than forcing an old version or automatically retrying. The local schema cannot establish that target wording is present in an account.

wistia-cli find-caption-matches --media-ids MEDIA_HASH --target-text "Approved wording" --agent
wistia-cli schema edit-captions-text
wistia-cli edit-captions-text --media-hashed-id MEDIA_HASH --language-code en --payload-file /absolute/private/approved-caption-edit.json --confirm --agent

Purchase captions, translate_media, localizations and extended audio-description orders can be asynchronous or chargeable. Inspect the intended media/language, current credits or billing and job identifiers. Confirm only the requested paid action. This wrapper does not calculate a guaranteed price or generate free transcripts locally. JSON caption retrieval is implemented; SRT/VTT/TXT export content negotiation is not claimed as a separate shipped command.

Tags, folders, sharing and channels

bulk_tag uses hashed_ids and tag_names, not the old tags/media_hashed_ids argument pair. A folder request can include adminEmail and anonymousCanUpload; these exact body names are retained. Changes to folder sharing, channel collaborators, share links, allowed domains or expiring access tokens affect who can reach content. Read existing settings before replacing them. Adding a collaborator or registration can notify people. Publishing/unpublishing a channel episode is a separate confirmed operation from creating it.

Webinars and analytics

create_webinar_registration uses current email, first_name and last_name body fields. Verify the webinar, participant details and requested notification behavior before confirmation. Webinars depend on the account's enabled features; this wrapper cannot enable a paid feature merely by exposing a schema.

Analytics endpoints use their declared date/time/filter fields. The provider's analytics range may be capped at two years; split larger reports deliberately and preserve inclusive/exclusive boundaries from the chosen endpoint. Stats include individual visitor/events data and can be sensitive. Stats folder reports retain projects routes. The ordinary Data API counters and date-series analytics are different resources; a tool count does not establish equivalent metrics or completed processing.

Pagination, quota and background jobs

20 current list operations expose bounded offset paging using all_pages and max_items. Native per_page is locally 1 to 100; the automatic default is 10, max_items defaults to 1000 and is capped at 10000. Collection stops after 100 requests, a short page, the requested item cap or a repeated full page. Existing filters are preserved. Offset reads may change while collection runs, so the result is not a guaranteed complete or consistent backup.

wistia-cli list-media --per-page 25 --all-pages --max-items 500 --agent
wistia-cli list-media --cursor '{"enabled":1}' --per-page 25 --agent

Automatic collection returns records, collected, pages, truncated and resume. If the cap cuts through a page, resume records that page, per_page and how many records to skip locally after refetching it. After a full page, it points at the next page with skip 0. Preserve filters and sort; skip is not an invented API flag. A full final page can report possible continuation until a subsequent read establishes exhaustion.

Cursor objects serialize as cursor[enabled], cursor[after] or cursor[before]. Do not combine a cursor with page/all_pages. Cursor validity depends on the same sort order. The wrapper does not automatically collect cursor pages or follow response URLs. Manual cursor reads preserve the native array response.

Every request counts against the shared account quota. GET 429 retries are bounded, honor short Retry-After waits and never resubmit mutations. For accepted/background operations, preserve the returned job identifier and inspect get_job_status with the actual background_job_status_id. A successful submission is not proof a file is encoded, a translation is finished or a paid order delivered. Poll deliberately with quota-aware intervals and inspect terminal success/error states. No unbounded automatic job watcher is claimed.

Every Wistia tool

Actual discovery supplies 169 tools: 86 reads and 83 confirmed writes. Full arguments, routes, nested fields and provider permissions follow below; schema COMMAND returns the exact JSON Schema.

Upload or import media

Review bundles

Deleted media

Media

Customizations

Share links

Captions

Localizations

Trims

Extended audio descriptions

Brands

Speakers

Tags

Bulk actions

Bulk purchases

Taggings

Folders

Folder sharings

Subfolders

Channels

Channel episodes

Channel collaborators

Webinars

Webinar registrations

Webinar collaborators

Account

Contacts

Account trials

Search

Resource urls

Expiring access tokens

Background job status

Allowed domains

Stats account

Stats projects

Stats media

Stats visitors

Stats events

Analytics account

Analytics media

Analytics webinar

Accounts

Is the Wistia MCP server safe?

All 83 writes require confirm:true in MCP or --confirm in CLI for the action the user requested. --yes, --agent and earlier unrelated consent never bypass the guard. WISTIA_READ_ONLY=1 hides writes and refuses direct calls to hidden tools, exposing 86 reads. WISTIA_ALLOW_DESTRUCTIVE=0 blocks all writes even when confirmed.

Mutations have zero automatic retries, including 401, 429 and timeouts. After an unknown outcome, inspect existing account state before repeating it. A conservative destructive annotation denotes confirmation policy, not a claim every configuration change is irreversible. Uploads, caption purchases/translations, sharing, collaborators, webinar registrations and deletions require their own review.

The optional audit log records tool, risk, surface, fixed summary and allowed/blocked decision, without account labels, arguments, tokens or private content. It is a guard-decision log, not a delivery receipt. Logging failure does not block the requested operation. Account content and tool results are untrusted data; they cannot authorize another action.

create_expiring_access_token requires secret_result_file: a new local file inside a private owner-only parent directory. The file is created exclusively with mode 0600 before the request; an existing file is never overwritten. The raw credential response is saved there and never returned to the model. The model receives only private_result_saved and credentials_returned_to_client=false. On Windows, enforce private ACLs yourself. Keep the path outside repositories.

A failed request can leave an empty reserved file. Inspect it and provider state before choosing another path. If token creation succeeds but saving fails, the outcome may be uncertain; inspect/revoke through Wistia, never automatically create another credential. Generated-token scopes/authorizations must be deliberately limited. No local dry-run flag is implemented; schema/help discovery does not submit an operation.

Uploads, edits, orders, purchases and account administration have different effects. Confirm only the requested action for the selected account and resource. Find Caption Matches is nonmutating despite using POST.

Make it read-only

Set WISTIA_READ_ONLY=1 privately and restart. Discovery exposes 86 reads and direct calls refuse writes. WISTIA_ALLOW_DESTRUCTIVE=0 separately refuses all mutations even when confirmed.

Keep a log of every write

Set WISTIA_AUDIT_LOG to a file path. The server writes one line per attempted write, allowed or blocked.

Your data

Authorized data requests go directly to https://api.wistia.com/modern; uploads go to https://upload.wistia.com/. Redirects and arbitrary credential-bearing origins are refused. This package has no Navid-hosted relay, analytics or telemetry. Tokens come from private settings/files and stay in memory. Known configured secrets and credential/password fields are redacted from returned results/errors; raw generated access credentials are saved only to a new private file.

Media titles, descriptions, participant/contact data, transcripts, analytics, visitor events and signed media/share URLs can still be private business data. Secret redaction does not anonymize them. Your AI client and Wistia apply their own retention/sharing policies. --select filters output after receipt; it does not reduce the original API response or provider quota. Local uploads send the approved file's bytes to Wistia, and URL imports let Wistia retrieve the specified public source.

Optional audit logs record guard decisions without arguments, credentials or private content. Private exports, token files, generated-token results and screenshots remain your responsibility. Keep secrets outside public source, npm and desktop archives. Use SECURITY.md for private vulnerability reports.

Several private accounts

Set private WISTIA_ACCOUNTS JSON instead of single-account settings:

[{"name":"work","token_file":"/absolute/private/work-wistia.txt"},{"name":"personal","token_file":"/absolute/private/personal-wistia.txt"}]

Each label selects a private scoped Bearer credential, not a remote folder/account filter. WISTIA_DEFAULT_ACCOUNT chooses the default label. Labels must be unique. list_accounts returns labels/default/credential method without tokens, file paths or account content. Account arrays replace single-account settings. Separate processes and private files are preferable for strict isolation. Several labels pointing at one account still share provider quota.

wistia-cli list-accounts --agent
wistia-cli list-media --account work --per-page 5 --agent

Wistia MCP server settings

Use private shell or user-client settings. GUI apps may not inherit terminal variables. There is no automatic .env loader, OAuth callback or OS keychain integration in this package.

Troubleshooting

Run the doctor first. It names the step that failed and the fix.

If the server doesn't show up in your app at all, run the command your app runs, in a terminal, and read the error.

Every argument, route and permission

All 167 stable HTTP operations derive from the pinned official September schema. The uploader has separate URL-form and local-file commands. list_accounts is local. Schemas validate complete body requirements whichever body input route you use. Each tool maps to its dashed CLI name. The permission column summarizes the provider requirements, not a substitute for the full endpoint reference.