reaper-mcp

Overview Schema Source Related Servers Discussions Admin

item

Manage media clips on REAPER tracks: list, update, import, split, delete, or duplicate clips, with beat-based timing and optional fade, gain, mute, and track placement controls.

Instructions

Media items on a track. action: list | update | import | split | delete | duplicate. Times are beats except fade_in_sec / fade_out_sec (seconds, REAPER native). update: gain_db, fades and fade_*_shape, loop, mute, position_beats (move), length_beats (trim the end), left_edge_beats (trim or extend the start; the content stays in place), dest_track_index (move to another track; returns the new indices), active_take. list shows take name, source file and take count. split cuts at at_beats (inside the item) and returns the pieces' item_indices. delete takes item_index or item_indices. duplicate copies the item (unpooled) to position_beats (default: right after it), optionally on dest_track_index. import uses a path already on the REAPER host; as_new_track=true makes new tracks. Item indices follow position, so re-list after edits that move items.

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": {
      "action": "<action>"
    },
    "name": "item"
  }
}

Input Schema

Name	Required	Description	Default
`loop`	No
`mute`	No
`path`	No
`action`	Yes
`gain_db`	No
`at_beats`	No
`item_index`	No
`active_take`	No
`fade_in_sec`	No
`start_beats`	No
`track_index`	No
`as_new_track`	No
`fade_out_sec`	No
`item_indices`	No
`length_beats`	No
`fade_in_shape`	No
`fade_out_shape`	No
`position_beats`	No
`left_edge_beats`	No
`dest_track_index`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed12 schema fields changedv0.6.0Oct 27, 2026

changedInput schema / properties / action / enum

Previous value: -[
-  "list",
-  "update",
-  "import"
-]New value: +[
+  "list",
+  "update",
+  "import",
+  "split",
+  "delete",
+  "duplicate"
+]

addedInput schema / properties / active_take

Added value: +{
+  "minimum": 0,
+  "type": "integer"
+}

addedInput schema / properties / at_beats

Added value: +{
+  "items": {
+    "minimum": 0,
+    "type": "number"
+  },
+  "type": "array"
+}

addedInput schema / properties / dest_track_index

Added value: +{
+  "minimum": 0,
+  "type": "integer"
+}

removedInput schema / properties / fade_in

Removed value: -{
-  "minimum": 0,
-  "type": "number"
-}

addedInput schema / properties / fade_in_sec

Added value: +{
+  "minimum": 0,
+  "type": "number"
+}

addedInput schema / properties / fade_in_shape

Added value: +{
+  "enum": [
+    "linear",
+    "fast_start",
+    "fast_end",
+    "fast_start_steep",
+    "fast_end_steep",
+    "s_curve",
+    "s_curve_steep"
+  ],
+  "type": "string"
+}

removedInput schema / properties / fade_out

Removed value: -{
-  "minimum": 0,
-  "type": "number"
-}

addedInput schema / properties / fade_out_sec

Added value: +{
+  "minimum": 0,
+  "type": "number"
+}

addedInput schema / properties / fade_out_shape

Added value: +{
+  "enum": [
+    "linear",
+    "fast_start",
+    "fast_end",
+    "fast_start_steep",
+    "fast_end_steep",
+    "s_curve",
+    "s_curve_steep"
+  ],
+  "type": "string"
+}

addedInput schema / properties / item_indices

Added value: +{
+  "items": {
+    "minimum": 0,
+    "type": "integer"
+  },
+  "type": "array"
+}

addedInput schema / properties / left_edge_beats

Added value: +{
+  "minimum": 0,
+  "type": "number"
+}

Changed5 schema fields changedv0.5.0Oct 23, 2026

changedInput schema / properties / action / enum

Previous value: -[
-  "list",
-  "update"
-]New value: +[
+  "list",
+  "update",
+  "import"
+]

addedInput schema / properties / as_new_track
```
Added value: +{
+  "type": "boolean"
+}
```
addedInput schema / properties / path
```
Added value: +{
+  "type": "string"
+}
```

addedInput schema / properties / start_beats

Added value: +{
+  "minimum": 0,
+  "type": "number"
+}

changedInput schema / required

Previous value: -[
-  "action",
-  "track_index"
-]New value: +[
+  "action"
+]

First observedv0.1.0Sep 20, 2026

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden and does well: it states split returns piece item_indices, duplicate is unpooled, dest_track_index returns new indices, import requires a host-local path, and item indices follow position so re-listing is needed after moves. It stops short of covering permissions, error behavior, or destructive warnings.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but appropriately sized for 20 parameters and six actions, and it is front-loaded with the resource and action list. It would be easier to scan as a bulleted action list, but every sentence adds actionable information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 20-parameter, multi-action tool with no annotations and no output schema, the description is largely complete, covering action semantics, units, side effects, and index behavior. The main gaps are the undocumented start_beats and track_index parameters, plus no mention of error or permission behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate and largely does: it explains units (beats vs seconds for fades), update fields (gain_db, fades, loop, mute, position_beats, length_beats, left_edge_beats, dest_track_index, active_take), split's at_beats, delete's item_index/indices, duplicate's position_beats, and import's path/as_new_track. It omits start_beats and track_index, leaving two parameters with no semantic explanation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Media items on a track' and enumerates the six supported actions (list, update, import, split, delete, duplicate), giving a specific resource and action set. It clearly distinguishes this tool from track-level siblings by scope, though it never names an alternative tool explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Each action has clear usage context: split cuts at at_beats, delete takes item_index or item_indices, duplicate copies the item to position_beats by default, and import uses a path on the REAPER host. It lacks explicit when-not-to-use guidance or sibling-tool routing, but the per-action context is strong enough for correct selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server