reaper-mcp

Overview Schema Source Related Servers Discussions Admin

run_lua

Execute Lua snippets inside REAPER to automate multi-step tasks in one call, with optional timeout and returned values.

Instructions

Run a Lua snippet inside REAPER (reaper in scope). Use return to send a value. Best for multi-step work that would otherwise be many round-trips. Errors carry the failing line. timeout (seconds, default 10, max 600): a snippet still running Lua after it is stopped with an error (what it did until then stays done); a call blocked inside REAPER (ExecProcess, a render, a dialog) can't be stopped. REAPER is frozen while it runs, so start long host commands in the background (io.popen('cmd > log 2>&1 &')) and poll instead.

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": {
      "code": "<code>"
    },
    "name": "run_lua"
  }
}

Input Schema

Name	Required	Description	Default
`code`	Yes
`timeout`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.5.0Oct 23, 2026
- addedInput schema / properties / timeout
```
Added value: +{
+  "maximum": 600,
+  "minimum": 1,
+  "type": "number"
+}
```
First observedv0.1.0Sep 20, 2026

TDQS

A4.5/5.0

Behavior5/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 so well: errors carry the failing line, the timeout stops a still-running Lua snippet but cannot interrupt a call blocked inside REAPER, work completed before the timeout remains done, and REAPER is frozen while the snippet runs. These are exactly the operational facts an agent needs before invoking arbitrary code execution.

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

Conciseness5/5

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

The description is front-loaded with purpose and use case, then covers return values, errors, timeout behavior, and the REAPER-frozen caveat without filler. The longer timeout sentence is dense but every clause carries operational meaning.

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 non-annotated arbitrary code execution tool with no output schema, the description is nearly complete: it covers scope, return mechanism, error reporting, timeout limitations, and host freezing. A minor gap is that it does not specify how returned values are serialized or whether there are restrictions on return types.

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

Parameters5/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 for both parameters, and it does. It explains that `code` is a Lua snippet with `reaper` in scope and that `return` sends a value; for `timeout` it adds the default (10), maximum (600), and non-obvious semantics about what can and cannot be interrupted.

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 states a specific verb and resource: running a Lua snippet inside REAPER with `reaper` in scope. It also signals the tool's niche as multi-step work that avoids many round-trips, though it never names the sibling tools (e.g., reaper_call or action) it is meant to replace.

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?

It clearly frames the best use case as multi-step work that would otherwise be many round-trips, and gives a concrete pattern for long host commands (start in background with io.popen and poll). It does not explicitly say when not to use this tool or name the dedicated sibling tools for single-step operations.

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

Deploy Server