Effekseer AI

简体中文 | English

Effekseer AI is an open-source Python CLI and Model Context Protocol (MCP) server for creating and editing Effekseer effects with AI agents. It uses the official EffekseerCore.dll API to work with .efkefc effect documents and export runtime .efk files.

Compatibility: this release is verified with Effekseer 1.80.6 for Windows. The Effekseer application, EffekseerCore.dll, samples, and assets are not included in this repository. See Compatibility.

What it does

• Create, open, save, and export .efkefc effects.

• Add, rename, move, and remove effect nodes.

• Discover and edit Core properties through stable node/... paths.

• Read and update editor-panel settings and scalar curve keyframes.

• Import image assets into an effect-local resources/ directory using relative paths.

• Serve the same operations to MCP-compatible AI clients over stdio.

Related MCP server: @perssona/orchestrator

What it does not do

• It does not bundle, patch, automate, or control the Effekseer GUI.

• It does not parse or rewrite the .efkefc binary format directly.

• It does not ship Effekseer DLLs, official samples, model converters, generated effects, or private project assets.

• It does not support Effekseer versions other than 1.80.6 as a verified configuration.

Requirements

• Windows 10 or later

• Python 3.11 or later

• .NET 9 Runtime

• Official Effekseer 1.80.6 Windows distribution

The selected Effekseer installation must contain Tool/bin/EffekseerCore.dll.

Installation

Clone the repository and install it into a virtual environment:

git clone https://github.com/laodeng000/effekseer-ai.git
cd effekseer-ai
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

Point the bridge at your own Effekseer 1.80.6 Tool/bin directory for the current terminal session:

$env:EFFEKSEER_AI_BIN_DIR = '<Effekseer-install>/Tool/bin'

EFFEKSEER_AI_BIN_DIR is required. The project deliberately never searches local drives for an installation.

CLI quick start

Create an effect, add a node, inspect settings, and export the runtime file:

effekseer-ai new .\effects\spark.efkefc
effekseer-ai node-add .\effects\spark.efkefc --name Spark
effekseer-ai settings-list .\effects\spark.efkefc node/root/0
effekseer-ai export .\effects\spark.efkefc .\effects\spark.efk

Use property-list or settings-list before writing a value. This prevents an AI client from guessing editor-specific property paths.

effekseer-ai property-list .\effects\spark.efkefc node/root/0
effekseer-ai property-get .\effects\spark.efkefc '<property-path>'
effekseer-ai property-set .\effects\spark.efkefc '<property-path>' '0.5'

All CLI results are JSON printed to standard output, which makes the commands suitable for scripts and agent tools.

CLI commands

Run effekseer-ai --help or effekseer-ai <command> --help for arguments and JSON input formats.

MCP server

After installation and environment configuration, start the stdio server:

effekseer-ai-mcp

Configure your MCP client to launch effekseer-ai-mcp with the same EFFEKSEER_AI_BIN_DIR environment variable. The available tools are documented in docs/mcp.md. This repository does not track any client-specific .codex, IDE, or local configuration files.

Development

python -m pytest
python -m pip wheel . --no-deps --wheel-dir .\dist

The default tests do not require an Effekseer installation. Tests that exercise the official Core assembly must be explicitly marked as integration tests and configured with EFFEKSEER_AI_BIN_DIR.

Privacy and security

Effekseer AI performs its document operations locally. It has no telemetry, analytics, account system, or network client. See PRIVACY.md and SECURITY.md.

License and third-party software

This bridge is licensed under the MIT License. Effekseer is a separate project with its own license and distribution terms; install it from the official project and review its license before redistribution.

Contributing

Issues and pull requests are welcome. Please read CONTRIBUTING.md before submitting changes.