ReaperMCP

ReaperMCP

Producción musical impulsada por IA en REAPER mediante el Protocolo de Contexto de Modelos

Inicio rápido • ¿Por qué ReaperMCP? • Características • Referencia de herramientas • Arquitectura • Registro de cambios • Contribuciones • Solución de problemas

ReaperMCP conecta cualquier asistente de IA compatible con MCP a REAPER, dándole control total sobre la producción musical. Habla con tu asistente de IA y él compone, mezcla, masteriza y mide tu música en tiempo real — la IA elige cada nota, ritmo y CC por sí misma.

181 herramientas en 26 módulos cubren el flujo de trabajo completo: composición y patrones MIDI, un pipeline de cortes vocales, FX y mezcla/masterización automática ajustada al género (35 perfiles de estilo), envíos y enrutamiento, y control de calidad en postproducción — edición por lotes, automatización con ReaScript, detección de silencios/clics.

Sin nube. Nada sale de tu máquina. ReaperMCP se ejecuta completamente en local mediante un puente IPC Lua basado en archivos dentro de REAPER — tu proyecto, audio y MIDI permanecen en tu computadora. Usa el cliente de IA que ya tengas (Claude Desktop, Claude Code, Cursor, cualquier cliente MCP) — ReaperMCP se encarga de REAPER.

Si esto te resulta útil, una estrella ayuda a que otros lo encuentren — ese es todo el presupuesto de marketing de este proyecto. ¿Quieres ayudar a mantenerlo? Haz clic en la insignia Sponsor arriba.

Demo

Funciona con

ReaperMCP funciona con cualquier cliente de IA que soporte el Protocolo de Contexto de Modelos:

• Claude Desktop — la aplicación de escritorio de Anthropic
• Claude Code — agente CLI
• Cursor — editor de código con IA y soporte MCP
• LM Studio — ejecuta modelos locales con acceso a herramientas MCP
• Cualquier otro cliente compatible con MCP

¿Por qué ReaperMCP?

• Control profundo, no solo reproducción. La mayoría de las integraciones de audio con IA exponen transporte básico — reproducir, detener, grabar. ReaperMCP expone la superficie de producción real de REAPER: mezcla/masterización automática consciente del género en 35 perfiles de estilo, un pipeline de cortes vocales, notación abreviada de patrones de batería y progresiones de acordes, y control de calidad en postproducción. La IA puede producir una pista de principio a fin, no solo pulsar botones en una que ya hiciste.
• 100% local. Sin llamadas a la nube, sin claves API, nada sale de tu máquina — REAPER y la IA se comunican mediante un puente basado en archivos en disco, no un servidor que no controlas.
• Mantenimiento activo. CI ejecuta la suite completa de pruebas en 3 sistemas operativos × 4 versiones de Python en cada cambio. Los problemas se leen, se discuten y se resuelven — no solo se registran y se olvidan.
• Componible con herramientas complementarias. Se combina con SongForge-MCP (generación local de música/voces con IA) y Audacity-MCP (limpieza de audio, masterización y transcripción local) — genera, produce y limpia sin salir de la misma conversación de IA.

Inicio rápido

1. Obtén ReaperMCP

Opción A: Haz clic en el botón verde Code arriba → Download ZIP → extrae a una carpeta — funciona sin nada preinstalado, es lo más fácil en una máquina nueva.

Opción B: Clona con git (te permite git pull para actualizaciones después):

Una instalación nueva de Windows no incluye git — compruébalo primero:

git --version

Si dice "not recognized", instálalo, luego cierra y reabre tu terminal:

winget install --id Git.Git -e --source winget

(winget ya viene con Windows 11 y Windows 10 actualizado. Si winget tampoco se encuentra, descarga el instalador directamente desde git-scm.com.)

macOS/Linux casi siempre tienen git ya — git --version para comprobar, o brew install git / sudo apt install git si no.

git clone https://github.com/xDarkzx/Reaper-MCP.git

Opción C: ¿Ya tienes Python? Instala el paquete publicado directamente desde PyPI:

pip install xdarkzx-reaper-mcp

Esto te da el comando reaper-mcp directamente — pero aún necesitarás reaper_scripts/reaper_mcp_server.lua para el Paso 3 abajo, ya que ese archivo no está incluido en el paquete de PyPI (descárgalo del repositorio, o descárgalo directamente).

2. Ejecuta el instalador

Windows: haz doble clic en install.bat en el Explorador de archivos, o — si ya estás en una terminal del paso git clone anterior — continúa en la misma ventana de PowerShell/Command Prompt:

cd Reaper-MCP
.\install.bat

macOS / Linux:

cd Reaper-MCP
bash install.sh

El instalador instala reaper-mcp localmente y opcionalmente configura Claude Desktop — sin necesidad de editar JSON manualmente.

{
  "mcpServers": {
    "reaper": {
      "command": "reaper-mcp"
    }
  }
}

3. Carga el script Lua en REAPER

¿Usaste el instalador de un clic? Ya está hecho — configura REAPER para cargar el script automáticamente en cada inicio. Solo abre (o reinicia) REAPER.

¿Instalación manual?

1. Abre REAPER
2. Ve a Actions → Show action list
3. Haz clic en Load ReaScript...
4. Navega hasta reaper_scripts/reaper_mcp_server.lua y selecciónalo
5. Haz clic en Run

Esto solo lo carga para la sesión actual — tendrás que volver a ejecutarlo cada vez que REAPER se reinicie. Consulta docs/INSTALLATION.md para la configuración de inicio automático.

4. Empieza a producir

Abre tu cliente de IA y empieza a hablar:

"Create 4 tracks: strings, brass, piano, and drums"
"Compose an 8-bar orchestral string arrangement in D minor"
"Add ReaEQ to the piano track and cut the low end below 200Hz"
"Set the tempo to 90 BPM and loop the first 8 bars"

REAPER debe estar abierto con el script Lua ejecutándose. ReaperMCP se comunica mediante IPC basado en archivos — no puede iniciar REAPER por ti.

Consulta la Guía de instalación completa para una configuración detallada en todas las plataformas y clientes MCP.

Características

181 herramientas en 26 módulos

Consulta docs/TOOLS.md para la referencia completa de herramientas con cada firma y una descripción de una línea para cada herramienta.

Perfiles de herramientas

La superficie predeterminada de 181 herramientas está diseñada para modelos frontera con todas las funciones. Modelos más pequeños/económicos (Groq Llama 3 tiene un límite de 128 herramientas, algunos modelos locales incluso menos) se truncarán silenciosamente. Configura REAPER_MCP_PROFILE en la configuración del servidor de tu cliente para elegir un subconjunto específico del flujo de trabajo:

{
  "mcpServers": {
    "reaper": {
      "command": "reaper-mcp",
      "env": { "REAPER_MCP_PROFILE": "mixing" }
    }
  }
}

Pipelines de mezcla y masterización

35 perfiles de estilo profesionales impulsan EQ automático, compresión, buses de reverberación, bombeo de sidechain y masterización — cada uno ajustado a objetivos LUFS de nivel industrial y carácter.

Estilos (35):

• EDM (11): melodic_dubstep, big_room, future_bass, future_house, deep_house, tech_house, progressive_house, dubstep, trap, drum_and_bass, trance
• Rock (6): alt_rock, classic_rock, pop_rock, hard_rock, punk, post_rock
• Pop (4): modern_pop, dance_pop, indie_pop, rnb_pop
• Electrónica (4): synthwave, lofi, ambient, hiphop
• Jazz (3): swing_jazz, jazz_fusion, latin_jazz
• Orquestal (3): classical_chamber, cinematic_trailer, ambient_orchestral
• Funk/Soul (4): classic_funk, motown_soul, neo_soul, disco_funk

Detección inteligente de plugins. fx_list_installed() inspecciona lo que hay en la máquina del usuario e informa del mejor EQ / compresor / reverberación / limitador / de-esser / puerta / saturación / multibanda / herramienta estéreo disponible — cubriendo FabFilter, Waves, iZotope, Valhalla, Softube, TDR, Slate, Melda, Soundtoys, Airwindows, plugins nativos de REAPER y hosts de rack comunes (Waves StudioRack, Blue Cat PatchWork, Kilohearts Snap Heap). Los usuarios pueden fijar preferencias de categoría → plugin mediante set_fx_preferences(...).

Composición impulsada por IA

La IA escribe cada nota, ritmo, curva de CC y keyswitch por sí misma usando las herramientas granulares de MIDI y FX anteriores. Un único archivo de instrucciones 00_core.md proporciona la superficie de herramientas, notación abreviada, referencia de CC de BBC Spitfire y consejos de mezcla por familia. La voicing, humanización, estructura y convenciones de género provienen del propio conocimiento musical de la IA.

Funciona bien junto a SongForge-MCP

¿Necesitas voces o una pista de acompañamiento completa y no quieres grabar ni licenciar nada? SongForge-MCP es un servidor MCP complementario que genera pistas vocales + instrumentales originales localmente (impulsado por ACE-Step 1.5 — sin servicio en la nube, sin suscripción, sin cuenta) y puede separar un stem vocal aislado. Ejecuta ambos servidores en la misma sesión de Claude Desktop: genera la pista allí, luego impórtala, arréglala y prodúcela aquí sin salir de la conversación.

Arquitectura

┌──────────────┐     stdio      ┌──────────────┐   file IPC    ┌──────────────┐
│  MCP Client  │◄──────────────►│  ReaperMCP   │◄────────────►│    REAPER    │
│(AI assistant)│    (JSON-RPC)  │   FastMCP    │  (JSON files) │  (Lua script)│
└──────────────┘                └──────────────┘               └──────────────┘

El servidor Python escribe comandos en command.json en un directorio temporal compartido; un script Lua dentro de REAPER consulta, ejecuta y escribe resultados en response.json. Sin sockets, sin puertos, sin exposición a la red.

Directorio IPC:

• Windows: %TEMP%\reaper_mcp
• macOS: $TMPDIR/reaper_mcp
• Linux: /tmp/reaper_mcp

Decisiones clave de diseño

• IPC basado en archivos — sin asignación de puertos, sin superficie de firewall.
• Despacho Lua estático — cada manejador es código explícito, sin load / dofile / loadstring.
• Registro dinámico de herramientas — coloca un módulo en reaper_mcp/tools/, exporta register(mcp) y se detecta automáticamente.
• Heartbeat + timeouts — el cliente detecta un REAPER obsoleto (sin actualización del archivo de bloqueo) y lanza un error tipado en lugar de colgarse.
• Límites conservadores por llamada — MAX_COMPOSE_TRACKS, MAX_TOTAL_NOTES_PER_CALL etc. mantienen cualquier comando individual por debajo de ~2 s del tiempo del hilo principal de REAPER.

Detalles completos — protocolo IPC, ciclo de vida de solicitudes, internals de registro, pipeline del motor de mezcla, catálogo de estilos — en docs/ARCHITECTURE.md.

Estructura del proyecto

Reaper-MCP/
├── reaper_mcp/
│   ├── main.py                     # FastMCP server entry (`reaper-mcp` command)
│   ├── tool_registry.py            # Auto-discovers tool modules
│   ├── reaper_client.py            # File-IPC client (lock, heartbeat, timeouts)
│   ├── cc_map.py                   # CC number translation helpers
│   ├── shorthand.py                # Compact composition notation parser
│   ├── instructions/
│   │   └── 00_core.md              # System-prompt instructions injected into MCP
│   ├── mix_engine/                 # Mixing + mastering pipelines
│   │   ├── __init__.py             # run_mix_pipeline
│   │   ├── master.py               # run_master_pipeline
│   │   ├── fix_mix.py              # Non-destructive mix repair
│   │   ├── detect.py               # FabFilter / REAPER stock detection
│   │   ├── fx_inventory.py         # Installed-plugin discovery
│   │   ├── plugins.py              # Plugin param translation
│   │   ├── profiles.py             # Legacy orchestral profiles
│   │   ├── profiles_v2.py          # Schema for 35 style profiles
│   │   └── catalog/                # Per-family style catalog
│   │       ├── edm.py              # 11 EDM subgenres
│   │       ├── rock.py             # 6 rock subgenres
│   │       ├── pop.py              # 4 pop subgenres
│   │       ├── electronic.py       # synthwave, lofi, ambient, hiphop
│   │       └── _shared.py          # Shared role → EQ/comp library
│   └── tools/                      # 26 modules, 181 auto-registered tools
│       ├── transport_tools.py      # Playback and recording (11)
│       ├── track_tools.py          # Track management + freeze (18)
│       ├── template_tools.py       # Track templates (4)
│       ├── project_tools.py        # Project/file operations + metadata (18)
│       ├── item_tools.py           # Media item management + batch apply (14)
│       ├── take_tools.py           # Takes (4)
│       ├── midi_tools.py           # MIDI notes, CC, program change (15)
│       ├── quantize_tools.py       # Quantize / humanize / ripple (3)
│       ├── marker_tools.py         # Markers, regions + batch apply (7)
│       ├── tempo_tools.py          # Tempo map markers (4)
│       ├── envelope_tools.py       # Automation envelopes (3)
│       ├── selection_tools.py      # Selection and loop (9)
│       ├── send_tools.py           # Sends and routing (8)
│       ├── fx_tools.py             # FX chain + params (15)
│       ├── inventory_tools.py      # fx_list_installed + set_fx_preferences (2)
│       ├── mix_tools.py            # engine_mix / engine_master / engine_fix_mix (3)
│       ├── sidechain_tools.py      # setup_sidechain (1)
│       ├── pipeline_tools.py       # Drum bus, parallel comp, vocal chain, stems (4)
│       ├── compose_tools.py        # get_track_instruments, analyze_score, compose_arrangement (3)
│       ├── compose_edit_tools.py   # wipe_all_midi, edit_section, rewrite_cc, … (9)
│       ├── patterns_tools.py       # create_drum_pattern, create_chord_progression (2)
│       ├── loops_tools.py          # scan_audio_folder, detect_common_bpm, load_loops (3)
│       ├── chops_tools.py          # Vocal chop pipeline + primitives (10)
│       ├── analysis_tools.py       # LUFS, clipping, spectrum, stereo field, silence/peak/region QC (7, optional deps)
│       ├── script_tools.py         # ReaScript discovery + execution (2)
│       ├── demo_tools.py           # demo_edm_project (1)
│       └── compose_helpers.py      # Shared helpers (no tools)
├── reaper_mcp_shared/
│   ├── constants.py                # IPC paths, timeouts, safety limits
│   ├── error_codes.py              # ReaperMCPError + ErrorCode enum
│   └── protocol.py                 # Command / response formatting
├── reaper_scripts/
│   └── reaper_mcp_server.lua       # Lua IPC bridge (runs inside REAPER)
├── docs/
│   ├── INSTALLATION.md             # Detailed setup for all platforms
│   ├── PROJECT_SETUP.md            # Template setups for orchestral / pop / EDM
│   ├── TOOLS.md                    # Complete tool reference
│   └── ARCHITECTURE.md             # IPC protocol, mix engine, design notes
├── tests/
├── install.bat / install.sh        # One-click installers
├── CHANGELOG.md
├── CONTRIBUTING.md
├── LICENSE
└── pyproject.toml

Configurando tu proyecto REAPER

ReaperMCP controla REAPER — pero necesitas instrumentos cargados para que la IA componga. La IA puede crear pistas y escribir MIDI, pero no puede navegar ni instalar plugins VST por ti.

Antes de empezar a componer

1. Abre REAPER y crea un nuevo proyecto
2. Añade pistas con tus instrumentos VST deseados (Kontakt, Spitfire, LABS, etc.)
3. Carga patches — p. ej., "Violin 1 Legato", "French Horn a4", "Grand Piano"
4. Guarda como plantilla (File → Save Project As Template) para no repetir esto cada vez

La IA usará get_track_instruments para detectar qué está cargado y componer para esos instrumentos automáticamente.

Consulta la Guía de configuración del proyecto completa para plantillas de instrumentos recomendadas (orquestal, pop/rock, EDM) y qué plugins cargar.

Limitación conocida — instrumentos multi-muestra / one-shot: la IA no puede ver qué sonido está mapeado a qué tecla dentro del navegador de muestras del plugin, ni si una tecla dada es un one-shot vs. una muestra sostenida — eso es estado privado del plugin que ningún host puede leer, cierto para la mayoría de VST/AU basados en muestras, no específico de este proyecto. Consulta Guía de configuración del proyecto § bibliotecas multi-muestra para la solución.

Solución de problemas

Desarrollo

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -x -q

# Run lint (real bugs + security patterns, not style/formatting)
ruff check .

Añadir nuevas herramientas

1. Crea un módulo en reaper_mcp/tools/ (o añade a uno existente)
2. Exporta una función register(mcp: FastMCP)
3. Define tus herramientas con decoradores @mcp.tool()
4. Eso es todo — el registro de herramientas lo descubre automáticamente al inicio

Consulta CONTRIBUTING.md para las pautas completas.

Comunidad

Convertir esto en una herramienta que todo usuario de REAPER use requiere más de una persona. Si estás usando ReaperMCP — incluso solo probándolo — únete al Discord: comparte lo que construiste, reporta lo que está roto, sugiere lo que falta, o simplemente pasa el rato con otras personas que hacen producción impulsada por IA. Las comunidades crecen cuando una persona le cuenta a otra que esto existe, así que si conoces a alguien que le sacaría provecho, envíale el enlace.

Soporte

Si ReaperMCP ha ayudado con tu producción musical, considera patrocinar:

Tu apoyo ayuda a mantener este proyecto mantenido y gratuito para todos.

Documentación

• Guía de instalación — Configuración detallada para Windows, macOS, Linux y cada cliente MCP compatible
• Guía de configuración del proyecto — Configura tu proyecto REAPER con instrumentos para composición con IA
• Referencia de herramientas — Cada herramienta agrupada por dominio, con una descripción de una línea y firma
• Arquitectura — Protocolo IPC, puente Lua, registro dinámico de herramientas, pipeline del motor de mezcla, catálogo de estilos
• Contribuir — Cómo añadir herramientas y contribuir
• Registro de cambios — Historial de versiones y notas de lanzamiento

¿Quieres saber cuándo sale una nueva versión? Haz clic en Watch → Custom → Releases en la parte superior de este repositorio — GitHub te notifica en cada Release etiquetado, sin el ruido de cada commit o issue.

Licencia

Apache License 2.0 — consulta LICENSE para detalles.

Construido por Daniel Hodgetts • 𝕏 @daehonz1

¿Necesitas una herramienta, plugin o integración personalizada construida así? Acepto proyectos de ingeniería selectos — búscame en el Discord y deja un mensaje, o abre un issue aquí.