istrunfa/reaper-mcp-server

REAPER MCP Server

Full REAPER DAW control via Model Context Protocol (MCP)

A comprehensive integration layer that exposes all features of Cockos REAPER Digital Audio Workstation through Anthropic's Model Context Protocol, enabling AI agents and automation systems to programmatically control every aspect of REAPER sessions.

📋 Project Status

Phase: Foundation (Week 1-3) Current Task: 1.1.1 - Install REAPER and create test project Progress: 0/40 tasks completed (0%) Estimated Duration: 14 weeks

🎯 Quick Start

View Project Plan

# See the comprehensive technical plan
cat REAPER_MCP_Server_Project_Plan.md

# Or view phase-by-phase breakdown
cat project-management/phases/README.md

Start Development

# 1. Install dependencies
npm install

# 2. Initialize project management system
npm run pm:init

# 3. Generate phase documentation
npm run pm:docs

# 4. Get your first task
npm run pm:next

# 5. Start the watcher (optional, for auto-tracking)
npm run pm:watch

🏗️ What Gets Built

Architecture Overview

┌─────────────────────────────────────┐
│     AI Agents & Clients              │
│  (Claude, Web Dashboard, Mobile)     │
└──────────────┬──────────────────────┘
               │ MCP Protocol
┌──────────────▼──────────────────────┐
│       MCP Server Layer               │
│    (Node.js/TypeScript)              │
│  • Tool Registration                 │
│  • Event Streaming                   │
│  • State Caching                     │
└──────────────┬──────────────────────┘
               │ gRPC / WebSocket / OSC
┌──────────────▼──────────────────────┐
│    REAPER Extension (C++)            │
│  • REAPER SDK Wrappers               │
│  • IPC Servers                       │
│  • Event Broadcasting                │
└──────────────┬──────────────────────┘
               │ REAPER SDK API
┌──────────────▼──────────────────────┐
│         REAPER DAW                   │
└──────────────────────────────────────┘

Key Components

Extension Layer (C++)

• Native REAPER plugin (DLL/dylib/so)
• Full REAPER API coverage
• gRPC, WebSocket, OSC servers
• Real-time event capture

MCP Server Layer (TypeScript)

• MCP protocol implementation
• 60+ tools for REAPER control
• Event subscription system
• State caching for performance

Communication Protocols

• MCP: AI agent interface (JSON-RPC)
• gRPC: High-performance commands
• WebSocket: Real-time events
• OSC: Meter data streaming

🎛️ Feature Coverage

See for complete list.

🔧 Project Management System

This project includes an intelligent, automated project management system with:

• ✅ Event Sourcing - Immutable activity log (JSONL)
• ✅ Rule Engine - Automatic milestone detection
• ✅ File Watcher - Real-time progress tracking
• ✅ Validation - Automated task completion checks
• ✅ Dashboard - Live progress visualization
• ✅ Phase Docs - Auto-generated markdown guides

Available Commands

npm run pm:next      # Get next task
npm run pm:exec      # Auto-execute task
npm run pm:watch     # Start background watcher
npm run pm:status    # View dashboard
npm run pm:validate  # Check task completion
npm run pm:report    # Create snapshot
npm run pm:sync      # Sync tracker.yaml
npm run pm:docs      # Generate phase docs

See: for complete guide.

📚 Documentation

Planning & Architecture

• - Full technical specification (3,591 lines)
• - Automation guide
• - 19 phase guides

Development Roadmap

Phase 1: Foundation (Weeks 1-3)

• Development environment setup
• Minimal REAPER extension
• Minimal MCP server

Phase 2: Core API (Weeks 4-6)

• Track operations
• Transport control
• Item operations
• State caching

Phase 3: Advanced Features (Weeks 7-9)

• FX & plugin management
• Envelope automation
• Real-time event streaming
• Transaction support

Phase 4: Production (Weeks 10-12)

• Authentication & security
• Error handling & logging
• Performance optimization
• Cross-platform testing

Phase 5: Release (Weeks 13-14)

• API documentation
• Example projects
• Deployment packaging
• Launch activities

🎯 Use Cases

AI-Assisted Mixing

// Claude agent suggests and applies EQ
await mcp.call("reaper.fx.insert", {
  trackId: "abc123",
  fxName: "ReaEQ",
  preset: "Vocal Clarity"
});

Automated Session Management

// Organize tracks by color and routing
const tracks = await mcp.call("reaper.track.list");
for (const track of tracks.drums) {
  await mcp.call("reaper.track.update", {
    trackId: track.id,
    color: "#ff5722",
    sendToTrack: "DRUM_BUS"
  });
}

Real-Time Monitoring

// Stream meter data for ML mastering
mcp.subscribe("track.meter", (event) => {
  console.log(`Track ${event.trackId}: ${event.peakDb} dB`);
});

🔒 Safety Features

• Undo Integration - All write operations wrapped in undo blocks
• Transaction Support - Atomic multi-operation groups
• Validation - Pre-flight checks and constraints
• Rate Limiting - Prevent resource exhaustion
• Authentication - API key and JWT support

🛠️ Technology Stack

Extension

• C++17
• CMake 3.20+
• REAPER SDK
• gRPC, WebSocket, OSC

Server

• Node.js 18+
• TypeScript 5+
• MCP SDK
• Protocol Buffers

Project Management

• Chokidar (file watching)
• js-yaml (config)
• Event sourcing (JSONL)
• CLI-first design

📦 Deliverables

Week 14 Outputs:

• ✅ macOS installer (.pkg + ReaPack)
• ✅ Windows installer (.exe + ReaPack)
• ✅ Linux packages (.deb, .rpm, AppImage)
• ✅ Docker images
• ✅ npm package: @istrunfa/reaper-mcp-server
• ✅ Complete API documentation
• ✅ 5 example projects
• ✅ Documentation website

🎓 Getting Help

Documentation:

• Start with npm run pm:next - the system will guide you
• Read
• Browse
• See for deep dive

Dashboard:

npm run pm:status
# Then open: project-management/00-MASTER-DASHBOARD.md

🚀 Ready to Build!

The project includes a complete roadmap with 40 tasks across 19 phases, guided by an intelligent project management system that tracks your progress automatically.

Start now:

npm run pm:init
npm run pm:next

The system will tell you exactly what to do next! 🎉

Project: REAPER MCP Server Version: 0.1.0 (Planning Phase) Started: 2025-11-08 Duration: 14 weeks License: MIT