Cavi Character Animator MCP
Turn recorded dialogue into a take you can still edit.
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/Heroand open the copy. SelectScene 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:
- Overview and setup
- Guides: your first result, project copies and ownership, importing and exporting, recovery and unknown outcomes and troubleshooting
- Reference: tools, results and errors, configuration and testing and evaluation
- Security model and version and support
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.