Avid Media Composer MCP Server

An independent, source-safe Model Context Protocol (MCP) server for Avid Media Composer project analysis, bin inspection, post-production metadata, and guarded editing automation.

Website · Setup · Capabilities · Security · npm

Format and workflow references: AVB files · AAF files · ALE files · EDL files · Avid bin locking · Compatibility matrix · AI and automation

Use it with an MCP client that can launch a local process or reach the configured authenticated HTTP server. The published 1.1.0 package provides analysis, interchange and bridge contracts, and it is what npx and the latest distribution tag install today. Version 1.2.0-rc.1 is cut in this repository and adds local media intelligence, installation helpers and a separate Windows native adapter, but it has not been published to npm yet; run it by building from source until that release candidate ships. A compatibility-rule result is not proof of this connector running on that host; native runtime evidence currently covers the qualified Windows Media Composer 2024.12 build described in implementation status. Mac implementation and host qualification are deferred.

The server also defines a 167-action editing catalog and a tested bridge protocol. Catalog actions require a compatible Extension that advertises each operation. The separate native adapter has its own bounded operations, authority checks and host qualification; the catalog does not describe its coverage.

Avid, Media Composer, MediaCentral, and related marks belong to Avid Technology, Inc. This independent project is not affiliated with or endorsed by Avid.

Development branch notes

These changes are not in the public 1.1.0 package, and the 1.2.0-rc.1 candidate that contains them is not on npm yet. Skip to Facts at a glance for the released server. See local setup for running this checkout and implementation status for what each addition has and has not proven.

Local media intelligence. This checkout indexes local media by content hash and adds bounded search, QC and reporting over that index: technical metadata and facets, black/freeze/silence and loudness measurement, contact sheets, thumbnail strips, transcript and speaker workflows, visual and people indexes, and verified copies or trims that leave the source untouched. avid_timecode_continuity assesses declared container and stream timecode across indexed files, handling drop-frame numbering for 29.97 and 59.94, and reports contiguous, gap, overlap or incomparable pairs from metadata alone. Longer analysis runs as cancellable local jobs whose status survives reconnecting; see audio sync research and watch folder recovery.

Saved-project inspection. Snapshots of saved AVB bins support paginated marker inspection with text, color declarations and explicitly unresolved or effect-input locations, timeline range and source-usage queries, sequence complexity, snapshot diffing, checksum verification against current bytes, filtered clip search described in saved snapshot search, and metadata-only file availability checks in saved locator availability. These are saved-file facts and exclude unsaved editor state.

Guarded native adapter. On the qualified Windows build the adapter performs bounded operations with capability checks, single-use tokens and post-write verification: clip Comments set and clear, AAF selects import, bin-column discovery, batch marker removal, clip duplication, clip renaming that checks the expected current name, media-volume declarations, and bin-scoped track and viewer inspection. Source-viewer loading verifies the requested MOB ID for the sequence case, while source-master identity mapping remains unresolved and Record and seek options are not exposed. None of this establishes full timeline editing or atomic undo.

Runtime and recovery. An isolated Python runtime can be installed into a new directory with a checksum-verified bootstrap and read-only status checks, so bin inspection no longer depends on ambient interpreter settings. Interrupted work is discoverable rather than replayed: watch folders recover crashed owner locks without discarding checkpoints, and source-clock preparation records attempts, publishes receipts as complete files and reports unresolved runs explicitly. Windows worker cancellation retains classified termination counts for diagnosis without storing raw command output.

Workflow skills. Original workflow skills cover ingest/QC, selects, review markers, turnover and export.

Facts at a glance

What works now

The following list describes the published analysis foundation. For the development branch's local visual search, transcription, people/speaker workflows, QC, saved snapshots and native operations, see the current implementation and remaining acceptance work. Tool discovery through tools/list is authoritative for the installed package; the development package currently exposes 145 tools, including offline and bridge tools.

• Recursively inventory and classify project, bin, setting, lock, interchange, sidecar, document, and media files.
• Detect active or orphaned .lck bin locks.
• Analyze AVB object graphs, bin views, mobs, tracks, clips, sequences, and metadata through pyavb.
• Analyze AAF mobs, slots, components, essence, descriptors, definitions, and metadata through pyaaf2.
• Parse every ALE heading, column, and row.
• Parse CMX-style EDL events, transitions, comments, clip names, and motion-effect lines.
• Validate source-marker packages and a strict static SVG-overlay subset before import.
• Compare transcript revisions locally without returning transcript text.
• Assess supplied DNx/DNx 4.0 turnover metadata and compatibility risks without transcoding.
• Preview conservative OTIO handoffs with local-media manifests, optional checksums, and relink blockers.
• Read an explicitly configured, allowlisted MediaCentral CTMS HAL registry without mutation.
• Read OTIO JSON structurally with bounded input/depth/object limits, flagging transitions, effects, retimes, nested timelines, media references, and audio-routing risks that need Media Composer confirmation.
• Decode text-like AVP/AVS/configuration files; fingerprint, measure, and string-extract opaque binary files without pretending their semantics are known.
• Inspect container and stream metadata through ffprobe, with optional frame/packet counting and SHA-256 hashing.
• Preview compound editing plans, classify risk, require destructive opt-in, and bind approval to an exact SHA-256 confirmation token.
• Report enabled authority, dependency health, source coverage, truncation, provider gates, and live bridge status.
• Evaluate Media Composer/Windows/macOS/architecture combinations against source-linked Avid rules.
• Detect standard Media Composer application locations on Windows and macOS.

Common use cases

• Ask an AI assistant to audit an Avid project before conform, turnover, migration, or archive.
• Summarize bins, sequences, tracks, clips, markers, and metadata from AVB or AAF evidence.
• Validate ALE, EDL, and OTIO interchange files and identify missing, opaque, malformed, or fidelity-sensitive data.
• Inventory project files, detect active or orphaned bin locks, and report collaboration risks.
• Inspect codec, container, duration, frame-rate, timecode, and stream metadata through ffprobe.
• Check whether a Media Composer version is qualified for the detected Windows or macOS environment.
• Preview a bounded edit plan and require exact confirmation before a connected extension can apply it.

What still requires Avid access

The Media Composer Extensions SDK (formerly Panel SDK) is the separate sanctioned integration path for the Extension bridge. SDK access and an installed compatible Extension remain prerequisites for that path. The development Windows native adapter uses the locally installed, checksum-qualified Avid binary and verifies the loopback listener owner; it does not require or distribute the private SDK. See native adapter setup and limits.

For the Extension path, until that bridge exists:

• avid_get_live_state fails closed with BRIDGE_NOT_CONNECTED.
• avid_apply_edit_plan fails closed even when the edit capability is enabled.
• An action appearing in the catalog is a planned contract, not evidence that Media Composer performed it.

See RESEARCH.md, supported versions, the capability matrix, and the bridge contract.

Architecture

flowchart LR
    Client[MCP client] -->|stdio| Server[TypeScript MCP server]
    Server --> Native[Native project / ALE / EDL / config analyzers]
    Server --> Python[Bounded Python inspector]
    Python --> AVB[pyavb]
    Python --> AAF[pyaaf2]
    Server --> Probe[ffprobe, optional]
    Server -->|qualified Windows build| Adapter[Guarded native adapter]
    Adapter --> Avid
    Server -->|signed plan token + local mailbox| Bridge[Media Composer Extension bridge]
    Bridge --> Avid[Media Composer project / bins / timeline]

Offline inspection, guarded native operations and the Extension bridge are separate paths. A missing bridge cannot silently fall back to native operations, UI automation or raw scripts.

Quick start

Requirements:

• Node.js 20 or newer
• Python 3.9 or newer for AVB/AAF analysis
• ffprobe on PATH for clip analysis
• A qualified Windows Media Composer build for development native operations, or a compatible protocol v3 Extension for bridge operations; see local setup

Install and run the stable release directly:

$env:AVID_MCP_ALLOWED_ROOTS = "C:\Users\you\Documents\Avid Projects"
$env:AVID_MCP_CAPABILITIES = "inspect"
npx -y avid-media-composer-mcp@latest

AVB and AAF inspection additionally needs Python plus the pinned packages in
python/requirements.txt. To install the unreleased development work from source:

git clone --branch codex/open-source-full-plan https://github.com/leancoderkavy/avid-media-composer-mcp.git
cd avid-media-composer-mcp
npm ci
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r .\python\requirements.txt
$env:AVID_MCP_ALLOWED_ROOTS = "C:\Users\you\Documents\Avid Projects"
$env:AVID_MCP_PYTHON = (Resolve-Path .\.venv\Scripts\python.exe).Path
npm run build
node .\dist\cli.js --doctor

Run the local stdio server:

node .\dist\index.js

Run the authenticated Streamable HTTP transport:

$env:MCP_AUTH_TOKEN = "<a strong random bearer token>"
npm run build
npm run start:http

The remote endpoint is /mcp; /health is intentionally unauthenticated for provider health
checks. Every MCP request requires Authorization: Bearer <token>.

The following example launches the published package. For this development checkout, generate configuration containing its absolute server entry instead:

node .\dist\cli.js --client generic --root "C:\Users\you\Documents\Avid Projects" --python "$env:AVID_MCP_PYTHON"

Use claude, cursor, vscode or lmstudio for the corresponding JSON format. Keep the checkout at a stable location. Generated configuration does not prove application onboarding; see client qualification and managed package installation.

Published-package example:

{
  "mcpServers": {
    "avid-media-composer": {
      "command": "npx",
      "args": ["-y", "avid-media-composer-mcp@latest"],
      "env": {
        "AVID_MCP_ALLOWED_ROOTS": "C:\\Users\\you\\Documents\\Avid Projects",
        "AVID_MCP_CAPABILITIES": "inspect"
      }
    }
  }
}

Start with AVID_MCP_CAPABILITIES=inspect. For Extension operations, after installing and testing a compatible bridge:

$env:AVID_MCP_CAPABILITIES = "inspect,edit"
$env:AVID_MCP_BRIDGE_DIR = "$env:LOCALAPPDATA\avid-media-composer-mcp\bridge"
$env:AVID_MCP_BRIDGE_AUTH_SECRET = "<the same unique 32+ character secret configured in the Extension>"

Protocol v3 rejects unauthenticated legacy bridge documents. Keep the secret in protected local
configuration and never place it in project files, logs, or source control.

Tools

The server also exposes:

• resource avid://catalog/edit-actions
• prompt avid-project-audit
• prompt avid-safe-edit

Project analysis example

Ask your MCP client:

Use avid_analyze_project on D:\Avid Projects\Episode_101. Include hashes, configurations, bins, and AAF. Do not analyze media payloads yet. Separate parsed evidence, opaque files, lock risks, and unavailable dependencies.

Large projects are bounded by explicit limits:

• AVID_MCP_MAX_FILES (default 10000)
• AVID_MCP_MAX_BINS (default 100)
• AVID_MCP_MAX_MEDIA_FILES (default 100)
• AVID_MCP_COMMAND_TIMEOUT_MS (default 30000)

Reports always identify truncation and per-format analyzed/unavailable/failed counts.

Optional PostHog operations telemetry

Set POSTHOG_API_KEY on the server to enable privacy-safe operational telemetry. It is
disabled by default and becomes a no-op when the key is absent.

$env:POSTHOG_API_KEY = "<PostHog project API key>"
$env:POSTHOG_HOST = "https://us.i.posthog.com"
$env:POSTHOG_DISTINCT_ID = "service:avid-media-composer-mcp"
npm run start:http

The server records avid_mcp_server_started, avid_mcp_connection_attempt,
avid_mcp_request, and avid_mcp_tool_call events for starts, authenticated or rejected
connection attempts, HTTP route/status/duration, and MCP tool name/outcome/duration/error
code. It does not send prompts, tool
arguments or results, paths, media or project names, bearer tokens, IP addresses, or person
profiles. Use a deployment secret for POSTHOG_API_KEY; never commit it.

See the PostHog event catalog and setup audit for event
properties, identity/privacy boundaries, and independent opt-in landing setup.

Safe edit workflow

1. Call avid_get_bridge_status.
2. Call avid_get_live_state.
3. Build a plan from actions the bridge lists in supportedEditOperations.
4. Include expectedState guards for project, sequence, bin, clip, or track identifiers.
5. Call avid_preview_edit_plan.
6. Review destructive/external actions and blockers.
7. Pass the unchanged plan and exact returned token to avid_apply_edit_plan.
8. Re-inspect the affected live state.

Example plan:

{
  "projectId": "project-uuid",
  "allowDestructive": false,
  "operations": [
    {
      "action": "bin.create",
      "arguments": { "name": "Selects" },
      "expectedState": { "projectId": "project-uuid" }
    }
  ]
}

Development

npm run typecheck
npm test
npm run test:python
npm run build
npm run smoke
npm run smoke:package
npm run pack:dry-run

Or run every release gate:

npm run check

Prepare or publish the npm package:

npm run publish:npm:dry-run
npm login --auth-type=web
npm run publish:npm -- --tag=next

The publish path validates the distribution tag, refuses duplicate versions, and verifies both the
published version and selected npm tag. GitHub publication additionally uses provenance and the
protected npm environment. See the release checklist.

The hosted Fly.io service runs with inspect authority and /data as its only readable root.
It cannot see projects on an editor workstation or control Media Composer there. Local project
analysis and editing require running the MCP beside Media Composer and connecting the Extension
bridge.

The test suite covers native parsers, binary configuration handling, allowed-root enforcement, project/lock analysis, stable edit tokens, simulated bridge application, MCP discovery/annotations/resources/prompts, and read-only AVB/AAF/OTIO fixtures.

Important format boundary

AVB, AVP, and AVS are not public, Avid-supported interchange specifications. pyavb can read and write many AVB structures, but independent reverse-engineered coverage is not equivalent to guaranteed compatibility with every Media Composer release or object type. This server therefore:

• opens AVB/AAF read-only for analysis;
• never writes an open or locked bin offline;
• preserves unrecognized or opaque evidence in reports;
• uses AAF/ALE/EDL/OTIO and the Extensions SDK as the preferred supported exchange/control surfaces.

Frequently asked questions

Is there an MCP server for Avid Media Composer?

Yes. This project provides a working MCP server for read-only Avid Media Composer project analysis. Guarded live editing is part of the protocol, but it requires a compatible Avid Extension bridge running inside Media Composer.

Can Claude, ChatGPT, or Codex inspect an Avid project?

Yes, when the AI client supports MCP and the server is allowed to read the project directory. The client can inventory files and inspect supported AVB, AAF, ALE, EDL, OTIO, configuration, and media evidence through the tools listed above.

Can this MCP server edit an Avid timeline?

Not by itself. The server can validate and preview editing plans, but live timeline or bin changes require the separate Extension bridge. If the bridge is absent, stale, or does not advertise an operation, the server rejects the request.

Does the server upload footage or project data?

The local stdio server does not need to upload project data. Analysis happens beside the project, subject to explicit allowed-root controls. A remote HTTP deployment can only read files available in its own environment and should use a strong bearer token.

Which Avid file formats are supported?

The server analyzes AVB through pyavb, AAF through pyaaf2, ALE and EDL with native parsers, AVP/AVS and related configuration files as text or bounded binary evidence, and media containers through ffprobe. Proprietary or opaque data is reported as such rather than guessed.

How is this different from UI automation?

It uses structured MCP tools, bounded filesystem access, explicit capabilities, compatibility rules, and a guarded extension protocol. It does not silently fall back to mouse-and-keyboard automation or claim an edit succeeded from a preview alone.

Project metadata

• Capability matrix
• Supported Media Composer versions
• Architecture
• Avid Extension bridge contract
• Research and primary sources
• Security policy
• Contributing
• Support
• Security audit
• Citation metadata

License

MIT. Python dependencies and optional media tools retain their own licenses.