Set Effect Property
set_effect_propertySet a single effect property on a Premiere Pro clip, using the property index for duplicate names and verified readback; input guards reject keyframed writes and out-of-range audio values.
Instructions
Set one effect property. Duplicate names require property_index from get_effect_properties. Colour values use [alpha, red, green, blue] and the lossless colour API; keyframed writes are refused. Readback reports verified, failed or committed_unverified; unreadable values are never reported as applied. Audio effect parameters (effects on audio clips other than built-in Volume, Channel Volume, Panner and Balance) take Premiere's normalized 0-1 value, not Hz, dB or ms; a number outside 0-1 is refused before the write when the current value is inside 0-1, unless allow_out_of_range_audio_value is true. valueScale describes the returned value; requestedValueScale is added when the request was on a different scale. Calibrate audio changes by rendering.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"node_id": "<node_id>",
"effect_name": "<effect_name>",
"property_name": "<property_name>",
"value": "<value>"
},
"name": "set_effect_property"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| value | Yes | Value to set. Use a number for scalar properties (for audio effects, the normalized 0-1 value get_effect_properties reports, not Hz, dB or ms), an array of numbers for vector properties such as Motion > Position or Anchor Point ([x, y]), a boolean for checkbox properties, the exact JSON string reported for a MOGRT text or graphic parameter, or that same JSON object if the client parsed it. | |
| node_id | Yes | Node ID of the clip | |
| effect_name | Yes | Display name of the effect (e.g., 'Motion', 'Opacity') | |
| property_name | Yes | Display name of the property; duplicate names require property_index. | |
| property_index | No | Optional property index from get_effect_properties; required when property_name is duplicated. | |
| idempotency_key | No | Optional client-chosen key (1-128 chars of A-Z a-z 0-9 . _ : -) for this intended edit. Pass a fresh key per edit and reuse it only when retrying that same edit, for example after a client-side timeout. A repeat with the same tool, key and arguments is not run again: while the first call is running it fails with IDEMPOTENCY_IN_PROGRESS (poll get_last_operations); after it finished it returns the original outcome marked replayed. A definite failure with nothing applied (receipt outcome not_applied) may be retried with the same key. Reusing a key with different arguments fails with IDEMPOTENCY_KEY_REUSED. Scoped to this MCP session (the stdio server process, or the HTTP server process when Streamable HTTP is stateless per request) and held in memory only (200 keys, 1 hour); it does not survive a restart or reconnect. Read-only invocations are never deduplicated. | |
| expected_cep_target | No | Optional reviewed CEP sequence/clip identity and exact tick ranges. Checked before every generated command; UXP refuses this CEP-only guard. | |
| expected_project_path | No | Optional absolute saved-project path. Every generated CEP command refuses before its body when the active project differs or is unsaved. UXP commands refuse this CEP-only guard; local-only tools do not inspect Premiere. Omit to keep existing behavior. | |
| allow_out_of_range_audio_value | No | Default false. Audio effect parameters normally use normalized 0-1 values, so a number outside 0-1 (for example 80 meant as Hz) is refused before the write while the current value is inside 0-1. Set true only when this parameter is known to accept that raw value. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ok | Yes | Whether the tool completed successfully. | |
| data | No | Tool-specific result data when ok is true; on failure, diagnostic detail when the tool provides it. | |
| tool | Yes | The registered MCP tool name. | |
| error | No | Failure detail when ok is false. | |
| receipt | No | Versioned common mutation receipt; success never implies rendered verification. | |
| idempotency | No | Present when idempotency_key deduplicated this call: replayed is true when the original outcome was returned instead of running again. |