ReaperMCP

ReaperMCP

Produção musical com IA no REAPER através do Model Context Protocol

Início Rápido • Por que ReaperMCP? • Recursos • Referência de Ferramentas • Arquitetura • Histórico de Alterações • Contribuindo • Solução de Problemas

O ReaperMCP conecta qualquer assistente de IA compatível com MCP ao REAPER, dando a ele controle total sobre a produção musical. Converse com seu assistente de IA e ele compõe, mixa, masteriza e mede sua música em tempo real — a IA escolhe cada nota, ritmo e CC por conta própria.

181 ferramentas em 26 módulos cobrem todo o fluxo de trabalho: composição e padrões MIDI, um pipeline de vocal chops, FX e mixagem/masterização automática ajustada por gênero (35 perfis de estilo), envios e roteamento, e controle de qualidade de pós-produção — edição em lote, automação ReaScript, detecção de silêncio/cliques.

Sem nuvem. Nada sai da sua máquina. O ReaperMCP roda inteiramente localmente através de uma ponte IPC Lua baseada em arquivos dentro do REAPER — seu projeto, áudio e MIDI permanecem no seu computador. Traga qualquer cliente de IA que você já usa (Claude Desktop, Claude Code, Cursor, qualquer cliente MCP) — o ReaperMCP cuida do REAPER.

Se isso for útil para você, uma estrela ajuda outras pessoas a encontrar o projeto — esse é todo o orçamento de marketing deste projeto. Quer ajudar a mantê-lo? Clique no selo Sponsor no topo.

Demonstração

Funciona Com

O ReaperMCP funciona com qualquer cliente de IA que suporte o Model Context Protocol:

• Claude Desktop — o aplicativo de desktop da Anthropic
• Claude Code — agente CLI
• Cursor — editor de código com IA e suporte a MCP
• LM Studio — execute modelos locais com acesso a ferramentas MCP
• Qualquer outro cliente compatível com MCP

Por que ReaperMCP?

• Controle profundo, não apenas reprodução. A maioria das integrações de áudio com IA expõe transporte básico — play, stop, record. O ReaperMCP expõe a superfície real de produção do REAPER: mixagem/masterização automática ciente de gênero em 35 perfis de estilo, um pipeline de vocal chops, notação abreviada de padrões de bateria e progressões de acordes, e controle de qualidade de pós-produção. A IA pode produzir uma faixa de ponta a ponta, não apenas apertar botões em uma que você já fez.
• 100% local. Sem chamadas de nuvem, sem chaves de API, nada sai da sua máquina — REAPER e a IA conversam através de uma ponte baseada em arquivos no disco, não um servidor que você não controla.
• Mantido ativamente. CI executa a suíte completa de testes em 3 SO × 4 versões de Python a cada alteração. Problemas são lidos, discutidos e resolvidos — não apenas registrados e esquecidos.
• Composável com ferramentas complementares. Combina com SongForge-MCP (geração local de música/vocais com IA) e Audacity-MCP (limpeza de áudio, masterização e transcrição local) — gere, produza e limpe sem sair da mesma conversa de IA.

Início Rápido

1. Obtenha o ReaperMCP

Opção A: Clique no botão verde Code acima → Download ZIP → extraia para uma pasta — funciona sem nada pré-instalado, mais fácil em uma máquina nova.

Opção B: Clone com git (permite git pull para atualizações depois):

Uma instalação nova do Windows não vem com git — verifique primeiro:

git --version

Se disser "not recognized", instale-o, depois feche e reabra seu terminal:

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

(winget já vem com Windows 11 e Windows 10 atualizado. Se winget também não for encontrado, baixe o instalador diretamente de git-scm.com.)

macOS/Linux quase sempre já têm git — git --version para verificar, ou brew install git / sudo apt install git se não tiver.

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

Opção C: Já tem Python? Instale o pacote publicado direto do PyPI:

pip install xdarkzx-reaper-mcp

Isso dá a você o comando reaper-mcp diretamente — mas você ainda precisará do reaper_scripts/reaper_mcp_server.lua para o Passo 3 abaixo, já que esse arquivo não está incluído no pacote PyPI (pegue-o do repositório, ou baixe diretamente).

2. Execute o instalador

Windows: clique duas vezes em install.bat no Explorador de Arquivos, ou — se você já estiver em um terminal da etapa git clone acima — continue na mesma janela do PowerShell/Command Prompt:

cd Reaper-MCP
.\install.bat

macOS / Linux:

cd Reaper-MCP
bash install.sh

O instalador instala reaper-mcp localmente e opcionalmente configura o Claude Desktop — sem necessidade de edição manual de JSON.

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

3. Carregue o script Lua no REAPER

Usou o instalador de um clique? Já está feito — ele configura o REAPER para carregar o script automaticamente a cada inicialização. Basta abrir (ou reiniciar) o REAPER.

Instalação manual?

1. Abra o REAPER
2. Vá em Actions → Show action list
3. Clique em Load ReaScript...
4. Navegue até reaper_scripts/reaper_mcp_server.lua e selecione-o
5. Clique em Run

Isso carrega apenas para a sessão atual — você precisará executá-lo novamente a cada reinício do REAPER. Veja docs/INSTALLATION.md para a configuração de inicialização automática.

4. Comece a produzir

Abra seu cliente de IA e comece a conversar:

"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"

O REAPER deve estar aberto com o script Lua em execução. O ReaperMCP se comunica através de IPC baseado em arquivos — ele não pode iniciar o REAPER por você.

Veja o Guia de Instalação completo para configuração detalhada em todas as plataformas e clientes MCP.

Recursos

181 Ferramentas em 26 Módulos

Veja docs/TOOLS.md para a referência completa de ferramentas com cada assinatura e uma descrição de uma linha para cada ferramenta.

Perfis de Ferramentas

A superfície padrão de 181 ferramentas é projetada para modelos frontier completos. Modelos menores/mais baratos (Groq Llama 3 tem limite de 128 ferramentas, alguns modelos locais ainda menos) serão truncados silenciosamente. Defina REAPER_MCP_PROFILE na configuração do servidor do seu cliente para escolher um subconjunto específico do fluxo de trabalho:

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

Pipelines de Mixagem e Masterização

35 perfis profissionais de estilo conduzem EQ automático, compressão, barramentos de reverb, pumping de sidechain e masterização — cada um ajustado para alvos LUFS e características padrão da indústria.

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
• Eletrônica (4): synthwave, lofi, ambient, hiphop
• Jazz (3): swing_jazz, jazz_fusion, latin_jazz
• Orquestral (3): classical_chamber, cinematic_trailer, ambient_orchestral
• Funk/Soul (4): classic_funk, motown_soul, neo_soul, disco_funk

Detecção inteligente de plugins. fx_list_installed() inspeciona o que está na máquina do usuário e informa o melhor EQ / compressor / reverb / limitador / de-esser / gate / saturador / multibanda / ferramenta estéreo disponível — cobrindo FabFilter, Waves, iZotope, Valhalla, Softube, TDR, Slate, Melda, Soundtoys, Airwindows, plugins nativos do REAPER e hosts de rack comuns (Waves StudioRack, Blue Cat PatchWork, Kilohearts Snap Heap). Usuários podem fixar preferências de categoria → plugin via set_fx_preferences(...).

Composição Impulsionada por IA

A IA escreve cada nota, ritmo, curva de CC e keyswitch por conta própria usando as ferramentas granulares de MIDI e FX acima. Um único arquivo de instruções 00_core.md fornece a superfície de ferramentas, notação abreviada, referência de CC do BBC Spitfire e dicas de mixagem por família. Voicing, humanização, estrutura e convenções de gênero vêm do próprio conhecimento musical da IA.

Funciona bem junto com SongForge-MCP

Precisa de vocais ou uma faixa de acompanhamento completa e não quer gravar ou licenciar nada? SongForge-MCP é um servidor MCP complementar que gera faixas vocais + instrumentais originais localmente (alimentado por ACE-Step 1.5 — sem serviço em nuvem, sem assinatura, sem conta) e pode separar um stem vocal isolado. Execute ambos os servidores na mesma sessão do Claude Desktop: gere a faixa lá, depois importe, arranje e produza mais aqui sem sair da conversa.

Arquitetura

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

O servidor Python escreve comandos em command.json em um diretório temporário compartilhado; um script Lua dentro do REAPER faz polling, executa e escreve resultados em response.json. Sem sockets, sem portas, sem exposição de rede.

Diretório IPC:

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

Decisões-chave de design

• IPC baseado em arquivos — sem alocação de portas, sem superfície de firewall.
• Dispatch Lua estático — cada handler é código explícito, sem load / dofile / loadstring.
• Registro dinâmico de ferramentas — coloque um módulo em reaper_mcp/tools/, exporte register(mcp), e ele é detectado automaticamente.
• Heartbeat + timeouts — o cliente detecta um REAPER travado (sem atualização do arquivo de lock) e levanta um erro tipado em vez de travar.
• Limites conservadores por chamada — MAX_COMPOSE_TRACKS, MAX_TOTAL_NOTES_PER_CALL etc. mantêm qualquer comando único sob ~2 s do tempo da thread principal do REAPER.

Detalhes completos — protocolo IPC, ciclo de vida de requisição, internals de registro, pipeline do motor de mixagem, catálogo de estilos — em docs/ARCHITECTURE.md.

Estrutura do projeto

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 Seu Projeto REAPER

O ReaperMCP controla o REAPER — mas você precisa de instrumentos carregados para a IA compor. A IA pode criar faixas e escrever MIDI, mas não pode navegar ou instalar plugins VST por você.

Antes de Começar a Compor

1. Abra o REAPER e crie um novo projeto
2. Adicione faixas com seus instrumentos VST desejados (Kontakt, Spitfire, LABS, etc.)
3. Carregue patches — ex.: "Violino 1 Legato", "Trompa Francesa a4", "Piano de Cauda"
4. Salve como template (Arquivo → Salvar Projeto como Template) para não repetir isso toda vez

A IA usará get_track_instruments para detectar o que está carregado e compor para esses instrumentos automaticamente.

Veja o Guia de Configuração de Projeto completo para templates de instrumentos recomendados (orquestral, pop/rock, EDM) e quais plugins carregar.

Limitação conhecida — instrumentos multi-sample/one-shot: a IA não consegue ver qual som está mapeado para qual tecla dentro do navegador de samples do próprio plugin, ou se uma determinada tecla é um one-shot vs. um sample segurado/sustentado — isso é estado privado do plugin que nenhum host pode ler, verdadeiro para a maioria dos VSTs/AUs baseados em sample, não específico deste projeto. Veja Guia de Configuração de Projeto § bibliotecas multi-sample para a solução alternativa.

Solução de Problemas

Desenvolvimento

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

# Run tests
pytest tests/ -x -q

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

Adicionando Novas Ferramentas

1. Crie um módulo em reaper_mcp/tools/ (ou adicione a um existente)
2. Exporte uma função register(mcp: FastMCP)
3. Defina suas ferramentas com decoradores @mcp.tool()
4. Pronto — o registro de ferramentas descobre automaticamente na inicialização

Veja CONTRIBUTING.md para diretrizes completas.

Comunidade

Transformar isso em uma ferramenta que todo usuário de REAPER procura exige mais do que uma pessoa. Se você está usando o ReaperMCP — mesmo apenas testando — venha participar do Discord: compartilhe o que construiu, reporte o que está quebrado, sugira o que está faltando, ou apenas converse com outras pessoas que fazem produção impulsionada por IA. Comunidades crescem quando uma pessoa conta para outra que isso existe, então se você conhece alguém que se beneficiaria disso, envie o link.

Suporte

Se o ReaperMCP ajudou na sua produção musical, considere patrocinar:

Seu apoio ajuda a manter este projeto mantido e gratuito para todos.

Documentação

• Guia de Instalação — Configuração detalhada para Windows, macOS, Linux e cada cliente MCP suportado
• Guia de Configuração de Projeto — Configurando seu projeto REAPER com instrumentos para composição por IA
• Referência de Ferramentas — Cada ferramenta agrupada por domínio, com descrição de uma linha e assinatura
• Arquitetura — Protocolo IPC, ponte Lua, registro dinâmico de ferramentas, pipeline do motor de mixagem, catálogo de estilos
• Contribuindo — Como adicionar ferramentas e contribuir
• Changelog — Histórico de versões e notas de lançamento

Quer saber quando uma nova versão sai? Clique em Watch → Custom → Releases no topo deste repositório — o GitHub notifica você em cada Release marcada, sem o ruído de cada commit ou issue.

Licença

Apache License 2.0 — veja LICENSE para detalhes.

Construído por Daniel Hodgetts • 𝕏 @daehonz1

Precisa de uma ferramenta, plugin ou integração personalizada construída assim? Aceito projetos seletivos de engenharia — venha me encontrar no Discord e deixe uma mensagem, ou abra uma issue aqui.