Skip to main content

Cavi Character Animator MCP

Turn recorded dialogue into a take you can still edit.

A mouse voice actor performs at a microphone as a crocodile puppet fills the monitor.

License: MIT PyPI weekly downloads

Your agent can prepare a project copy, import a puppet PSD or dialogue WAV, and run Adobe’s lip sync on scene audio. Refine the take in Character Animator, then have the agent check the exported PNG frames and WAV against your handoff recipe.

Install · Try your first take · Read the guides

Install

Requires macOS, Adobe Character Animator installed and signed in, the Swift command-line compiler (xcode-select --install; the server compiles its native helper on first use) and Python 3.15 or later with uv. The MCP host needs Accessibility access; capture also needs Screen Recording access. You supply your own licensed Adobe applications.

uv tool install cavi-character-animator-mcp

Upgrade with uv tool upgrade cavi-character-animator-mcp. To work from a checkout instead, see CONTRIBUTING.md.

Quickstart

Register the stdio server with your MCP client and set the workspace:

{
  "mcpServers": {
    "character-animator": {
      "command": "cavi-character-animator-mcp",
      "env": {"CAVI_ADOBE_WORKSPACE": "/absolute/path/to/workspace"}
    }
  }
}

If your client does not inherit your shell's PATH, use the absolute path that command -v cavi-character-animator-mcp prints.

Start with a closed Character Animator project whose scene already contains a puppet and its dialogue. Ask your agent for one take you can review.

Prepare a copy of projects/Hero and open the copy. Select Scene 1, run Character Animator’s lip sync from the scene audio, and inspect the result.

The first result guide walks through that take and its export. The setup guide covers macOS permissions and workspace paths.

What you can do

  • Keep the original handy. Prepare a separate, editable copy of a closed project. The server checks the copied files and confirms which project the session owns before editing.
  • Work with your own puppet and dialogue. Import a puppet PSD or a dialogue WAV and use Character Animator’s scene and lip-sync actions on the selected items.
  • Check the handoff. Request a PNG sequence and WAV. Check frame order, file hashes, and audio timing against an explicit recipe, then save a receipt for the output files.
  • See where the work landed. Inspect the open project, capture the app window, and review recorded operations before continuing an interrupted action.
Tool Purpose
character_status Report whether the application is running and reachable.
inspect Read the process, project root, native controls, visible Project panel rows, timeline selection and unresolved operation state.
capture Capture the Character Animator window with text recognition into a new workspace directory and return it as an image.
session_control Inspect, claim, renew, release or resume ownership of an open project.
project_prepare_copy Copy a closed .chproj tree into the workspace and verify its file hashes.
project_open_prepared_copy Open a prepared copy in the application.
project_save_copy Save an owned project as a new copy.
import_media Import a puppet PSD or a dialogue WAV and report the new Project panel row.
scene_action Run one menu action on the selection: add to a new scene, create a take from scene audio, compute lip sync, set the work area to the selection or export PNG and WAV.
scene_export Export a PNG Sequence and WAV of the owned scene into a new workspace directory and report the written files.
project_select Select a puppet, audio or scene row in the Project panel by name.
operation_control Inspect, verify or continue a recorded native operation.
export_inspect Validate exported PNG and WAV files, their hashes and the dialogue sample timing.
export_ingest Write a pinned media receipt and a measured audio descriptor for the exported files.

See the tool reference for parameters and results.

Closed projects and recovery

For a closed Character Animator project, prepare a copy with project_prepare_copy, open that prepared copy, inspect its project root and claim it with session_control before editing. An import is confirmed when its puppet or audio row appears in the Project panel; an unknown import whose row appears later is resolved with operation_control reconcile_import, with the application still running. After a process exits, the operation control and session control tools provide explicit reconciliation and lease release actions; they preserve unknown outcomes and project files. To record a cancelled import, the server asks you directly when your MCP client supports elicitation.

Keep workspace ownership records private. Each native operation is recorded before it runs. If an operation reports an unknown outcome, inspect the application and outputs or reconcile the recorded operation before trying again. See project copies and ownership and recovery and unknown outcomes.

Documentation

The documentation source is in docs/character-animator-mcp/source:

Configuration

Variable Meaning
CAVI_ADOBE_WORKSPACE Absolute directory every tool path is relative to. Required.
CAVI_ADOBE_DATA Private server state: native helper builds and Character Animator journals. Defaults to ~/.local/share/cavi-adobe-mcp.
CAVI_CHARACTER_ANIMATOR_APP The Character Animator .app to use.

Without an override the server uses the newest installed version under /Applications with the application's bundle identifier. An override that names another application is refused with APP_IDENTITY_MISMATCH.

Security

The server speaks MCP over stdio, sends no telemetry and uses no accounts. It controls Character Animator with the Accessibility and, for capture, Screen Recording permissions of the MCP host, so run it only for clients you trust. Tool paths are confined to the workspace, and the tools that change the project refuse any project that is not an owned copy. See the security model and SECURITY.md.

Contributing

See CONTRIBUTING.md for setup, checks and the rules for changes. This project follows the Code of Conduct.

License

MIT. See LICENSE.

Trademarks

Adobe and Character Animator are either registered trademarks or trademarks of Adobe in the United States and/or other countries. This project is not affiliated with, endorsed by, or sponsored by Adobe. It does not include or redistribute Adobe software, puppets or project files; you supply your own licensed application.

Metadata

Release files for cavi-character-animator-mcp 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cavi-character-animator-mcp 0.2.0
File Size Uploaded Provenance Actions
cavi_character_animator_mcp-0.2.0.tar.gz 129.5 kB With provenance Details for cavi_character_animator_mcp-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cavi-character-animator-mcp 0.2.0
File Interpreter ABI Platform Actions
cavi_character_animator_mcp-0.2.0-py3-none-any.whl Python 3 none any Details for cavi_character_animator_mcp-0.2.0-py3-none-any.whl

Total release size: 205.0 kB

Release files / cavi_character_animator_mcp-0.2.0.tar.gz

Download URL cavi_character_animator_mcp-0.2.0.tar.gz
Size 129.5 kB
Tags Source
SHA-256 checksum
How to use checksums
066a4e8899c4eacfc7175b23b1c8778e202fe9b01e10b3be608eb02f8c184376
BLAKE2b-256 checksum
How to use checksums
585b2cb2d459f2c7c24c2cc84d3c0dd1433a46e7fd5790b5a9db4afe8f5c1637
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Release files / cavi_character_animator_mcp-0.2.0-py3-none-any.whl

Download URL cavi_character_animator_mcp-0.2.0-py3-none-any.whl
Size 75.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
32c0743cd481204706341fddaa1e45810407607f9d848c813095a0f19888f3fa
BLAKE2b-256 checksum
How to use checksums
24cf447520047bdf1db9fa6a9554d376368c5e7814a8f1188abe7f010304165e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Security for cavi-character-animator-mcp 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for cavi_character_animator_mcp-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page