🎸 MIDI Guitar Pedal MCP Server

A powerful Model Context Protocol (MCP) server that bridges AI assistants with MIDI guitar pedals. Control your guitar effects using natural language through any MCP-compatible AI assistant!

🚀 What is this?

MIDI MCP lets you control guitar pedals using natural language:

You say: "Make my delay sound brighter"
AI Assistant: Interprets and generates MidiCommand(channel=1, cc=5, value=100)
MCP Server: Executes the command → Sends B0 05 64 to your pedal
Your Pedal: Filter frequency increases, delay sounds brighter! 🎵

✨ Features

🎛️ Persistent Pedal Knowledge - Store MIDI CC mappings for any guitar pedal
🤖 AI Assistant Integration - Works with Claude, ChatGPT, or any MCP-compatible AI
🎵 Real MIDI Output - Sends actual MIDI commands to hardware
📦 Pre-loaded Pedals - Includes Meris LVX delay, Mercury X reverb, Enzo X synthesizer, Neural DSP Quad Cortex, and Eventide H90 Harmonizer with full MIDI CC tables
🎛️ Preset Creation - Create complete presets via multiple MIDI CC commands sent in sequence from natural language descriptions
🧪 Fully Tested - 25 focused tests covering real functionality
⚡ Clean Architecture - Separation between AI intelligence and MIDI execution

🏗️ Architecture

┌─────────────┐  Pedal Config Query    ┌─────────────┐    MIDI Commands    ┌─────────────┐
│             │ ────────────────────── │             │ ─────────────────── │             │
│ AI Assistant│   get_pedal("lvx")     │ MCP Server  │  B0 05 64 (bytes)   │ Guitar Pedal│
│             │ ◄───────────────────── │             │ ◄────────────────── │             │
└─────────────┘    CC Mappings         └─────────────┘    MIDI Response    └─────────────┘
     │                                        ▲
     └─ "make it brighter" → CC5=100 ─────────┘

MCP Server exposes pedal configurations and executes MIDI. AI Assistant translates natural language to MIDI using the exposed knowledge.

🚀 Quick Start

Prerequisites

Java 8+
Maven 3.6+
MIDI interface (for real pedals) or use mock mode for testing

1. Clone and Build

git clone https://github.com/guyko/midimcp.git
cd midimcp
mvn compile

2. Run the MCP Server

mvn exec:java
# or
./run-server.sh

3. Connect Your AI Assistant

Claude Desktop Integration

Step 1: Build the project

cd /path/to/midimcp
mvn compile

Step 2: Configure Claude Desktop Add this configuration to your Claude Desktop config file:

Location: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "midi-guitar-pedals": {
      "command": "/path/to/your/midimcp/start-mcp-wrapper.sh",
      "args": []
    }
  }
}

Replace /path/to/your/midimcp/ with your actual project directory path.

Step 3: Restart Claude Desktop Completely quit and restart Claude Desktop for the configuration to take effect.

Step 4: Test the connection After restarting, you should see the "midi-guitar-pedals" server available. You can test it by asking Claude to:

"List available guitar pedals"
"Show me the parameters for the LVX delay"
"Execute a MIDI command to make the delay brighter"

Other MCP-Compatible AI Assistants

Configure your AI assistant to connect to the MCP server using the appropriate MCP client for your platform. The server provides these tools:

execute_midi_command - Send single MIDI CC command
execute_midi_commands - Send multiple commands in sequence
get_pedal - Get pedal information and parameters
list_pedals - Show available pedals
add_pedal - Add new pedal configurations
generate_h90_program - Generate H90 program files (.pgm90 format) for upload to Eventide H90
send_sysex - Send sysex data directly to MIDI devices for preset uploads or custom messages

🎵 Example Usage

Adding a New Pedal

{
  "tool": "add_pedal",
  "arguments": {
    "manufacturer": "Strymon",
    "modelName": "Timeline", 
    "parameters": [
      {"name": "Mix", "ccNumber": 1, "description": "Wet/dry mix"},
      {"name": "Time", "ccNumber": 2, "description": "Delay time"}
    ]
  }
}

Executing MIDI Commands

The AI assistant converts "make it brighter" into:

{
  "tool": "execute_midi_command",
  "arguments": {
    "pedalId": "meris_lvx",
    "ccNumber": 5,
    "value": 100,
    "description": "Increase filter frequency for brightness"
  }
}

Result: B0 05 64 sent to pedal → Filter opens up → Brighter delay sound! ✨

Batch Commands for Complex Sounds

AI assistant interprets "give me a vintage slapback" and sends:

{
  "tool": "execute_midi_commands", 
  "arguments": {
    "pedalId": "meris_lvx",
    "commands": [
      {"ccNumber": 0, "value": 1, "description": "Switch to Tape engine"},
      {"ccNumber": 3, "value": 35, "description": "Short delay time"},
      {"ccNumber": 4, "value": 20, "description": "Low feedback"},
      {"ccNumber": 1, "value": 30, "description": "Balanced mix"}
    ]
  }
}

Mercury X Reverb Control

AI assistant interprets "create a lush cathedral reverb" and sends:

{
  "tool": "execute_midi_commands", 
  "arguments": {
    "pedalId": "meris_mercury_x",
    "commands": [
      {"ccNumber": 32, "value": 25, "description": "Select Cathedra reverb structure"},
      {"ccNumber": 33, "value": 100, "description": "Long decay time"},
      {"ccNumber": 1, "value": 75, "description": "High wet mix"},
      {"ccNumber": 15, "value": 40, "description": "Medium predelay time"}
    ]
  }
}

Enzo X Synthesizer Control

AI assistant interprets "create a warm polysynth pad" and sends:

{
  "tool": "execute_midi_commands", 
  "arguments": {
    "pedalId": "meris_enzo_x",
    "commands": [
      {"ccNumber": 22, "value": 40, "description": "Switch to Poly Synth mode"},
      {"ccNumber": 24, "value": 64, "description": "OSC1 triangle wave"},
      {"ccNumber": 39, "value": 80, "description": "Filter frequency for warmth"},
      {"ccNumber": 55, "value": 90, "description": "Slow amplitude attack"}
    ]
  }
}

Quad Cortex Scene Control

AI assistant interprets "switch to clean scene and enable reverb" and sends:

{
  "tool": "execute_midi_commands", 
  "arguments": {
    "pedalId": "neural_dsp_quad_cortex",
    "commands": [
      {"ccNumber": 43, "value": 1, "description": "Switch to Scene B"},
      {"ccNumber": 36, "value": 127, "description": "Enable footswitch B (reverb)"},
      {"ccNumber": 47, "value": 1, "description": "Switch to Scene mode"}
    ]
  }
}

Preset Creation via CC Commands

Create complete pedal presets by sending multiple MIDI CC commands in sequence. The AI assistant interprets natural language descriptions and creates presets by sending targeted CC command sequences that configure all aspects of the pedal's sound.

How Preset Creation Works

AI queries pedal capabilities via get_pedal to understand available CC parameters
AI interprets natural language like "warm vintage slapback delay"
AI sends multiple CC commands via execute_midi_commands to configure the preset
User hears changes in real-time as each CC command adjusts pedal parameters
User saves preset on pedal when satisfied with the sound

LVX Delay Preset Creation

AI assistant interprets "create a warm vintage slapback delay" and sends:

{
  "tool": "execute_midi_commands",
  "arguments": {
    "pedalId": "meris_lvx",
    "commands": [
      {"ccNumber": 16, "value": 86, "description": "Switch to Tape delay engine"},
      {"ccNumber": 1, "value": 85, "description": "High wet mix signal"},
      {"ccNumber": 15, "value": 35, "description": "Short slapback timing"},
      {"ccNumber": 19, "value": 25, "description": "Low feedback for single repeat"},
      {"ccNumber": 21, "value": 15, "description": "Subtle tape warble modulation"},
      {"ccNumber": 80, "value": 75, "description": "Warm/dark filter tone"},
      {"ccNumber": 62, "value": 16, "description": "Light dynamics compression"}
    ]
  }
}

Result: Pedal configured in real-time! User can tweak and save the preset on the pedal itself. 🎛️

Mercury X Reverb Preset Creation

AI assistant interprets "create a large cathedral reverb with warm predelay" and sends:

{
  "tool": "execute_midi_commands",
  "arguments": {
    "pedalId": "meris_mercury_x",
    "commands": [
      {"ccNumber": 5, "value": 1, "description": "Select Cathedra reverb structure"},
      {"ccNumber": 1, "value": 90, "description": "High wet mix signal"},
      {"ccNumber": 11, "value": 95, "description": "Very long decay time"},
      {"ccNumber": 12, "value": 45, "description": "Medium room size predelay"},
      {"ccNumber": 13, "value": 40, "description": "Noticeable predelay separation"},
      {"ccNumber": 25, "value": 2, "description": "Warm tube preamp type"},
      {"ccNumber": 31, "value": 1, "description": "High cut filter for warmth"},
      {"ccNumber": 33, "value": 85, "description": "Remove harsh frequencies"}
    ]
  }
}

Enzo X Synthesizer Preset Creation

AI assistant interprets "create a classic poly synth pad with slow attack" and sends:

{
  "tool": "execute_midi_commands",
  "arguments": {
    "pedalId": "meris_enzo_x",
    "commands": [
      {"ccNumber": 5, "value": 1, "description": "Select Poly Synth mode"},
      {"ccNumber": 1, "value": 75, "description": "Balanced mix level"},
      {"ccNumber": 11, "value": 1, "description": "Sawtooth oscillator 1"},
      {"ccNumber": 17, "value": 2, "description": "Triangle oscillator 2"},
      {"ccNumber": 24, "value": 70, "description": "Medium filter brightness"},
      {"ccNumber": 25, "value": 20, "description": "Subtle filter resonance"},
      {"ccNumber": 29, "value": 80, "description": "Slow amplitude attack"},
      {"ccNumber": 31, "value": 85, "description": "High sustain level"},
      {"ccNumber": 32, "value": 60, "description": "Medium release time"}
    ]
  }
}

Benefits: Real-time preset creation with immediate audio feedback! Users hear every parameter change and can fine-tune before saving. 🎵

H90 Harmonizer Program Creation

For the H90, program creation works differently - it generates downloadable .pgm90 files:

{
  "name": "generate_h90_program",
  "arguments": {
    "name": "Ethereal Pad",
    "algorithmA": {
      "algorithmNumber": 60,
      "parameters": {
        "mix": "0.8",
        "size": "0.9",
        "decay": "0.85"
      }
    },
    "algorithmB": {
      "algorithmNumber": 37,
      "parameters": {
        "intensity": "0.6",
        "depth": "0.4",
        "speed": "0.3"
      }
    },
    "routing": {
      "mode": "PARALLEL"
    }
  }
}

H90 Difference: Creates binary .pgm90 files for upload rather than real-time MIDI control, matching H90's program-based architecture. 📁

🎛️ Included Pedals

Meris LVX Delay (Pre-loaded - MIDI Channel 2)

Complete MIDI CC table including:

Engine Selection (Vintage, Tape, Digital, Sweep, Reverse, Pitch)
Global Controls (Mix, Level, Time, Feedback)
Filtering (Filter, Low Cut)
Modulation (Rate, Depth)
Stereo (Width, Ping Pong)
Advanced (Diffusion, Smear, Drive)

Meris Mercury X Reverb (Pre-loaded - MIDI Channel 1)

Complete MIDI CC table including:

8 Reverb Structures (Ultraplate, Cathedra, Spring, 78 Room/Plate/Hall, Prism, Gravity)
Predelay System (Time, Feedback, Cross Feedback, Modulation, Damping, Dry Blend)
Processing Elements (Dynamics, Preamp, Filter, Pitch, Modulation)
Flexible Routing (Pre+Dry, Pre, Feedback, Pre Tank, Post locations)
Expression Control (6 assignable expression pedal mappings)
Advanced Features (Gate controls, Hold Modifier, Tuner, MIDI Clock sync)

Meris Enzo X Synthesizer (Pre-loaded - MIDI Channel 3)

Complete MIDI CC table including:

5 Synth Modes (Mono Synth, Poly Synth, Arp Synth, Dry Mono, Dry Poly)
Dual Oscillators (Independent wave shapes, pitch offset, detune, cross modulation)
Advanced Filters (Ladder, State Variable, Twin with noise injection)
ADSR Envelopes (Filter and Amplitude envelopes with full ADSR control)
Processing Elements (Drive, Ambience, Modulation with flexible routing)
Modulation Effects (Chorus, Flanger, Vibrato, Phaser, Ring Mod)
MIDI Note Control (Full polyphonic MIDI keyboard support, aftertouch)

Neural DSP Quad Cortex (Pre-loaded - MIDI Channel 4)

Complete MIDI CC table including:

6 DSP Cores (Most powerful floor modeler, 4-instrument processing)
Neural Capture Technology (Capture real amps and effects)
Multiple Modes (Preset, Scene, Stomp, Hybrid modes)
8 Footswitches (A-H with individual enable/bypass control)
Advanced Looper X (Up to 4+ minutes, punch in/out, reverse, quantize)
Expression Control (2 expression pedals with MIDI CC assignment)
Program Management (Scene selection, tempo control, tuner, gig view)

Eventide H90 Harmonizer (Pre-loaded - MIDI Channel 8)

Complete MIDI CC table and unique program generation:

70+ Algorithms across 9 categories (Delay, Distortion, EQ, Harmonizer, Looper, Modulation, Multi, Reverb, Synth, Utility)
Dual Algorithm Engine (Run two algorithms simultaneously with independent control)
Program File Generation (Creates .pgm90 files for upload to H90 via generate_h90_program tool)
Advanced Routing (Series A→B, Series B→A, Parallel, Series with crossfade)
Expression Control (Assignable expression pedal with multiple mapping options)
Real-time Control (Algorithm switching, parameter control, bypass, mix levels)
Legendary Eventide Effects (H910/H949 pitch shifters, Blackhole reverb, UltraTap delay, Crystals harmonizer)

🎵 Real-World Example: Microcosm-Style LVX Preset

User Request: "I'd like you to program my LVX to behave like a Microcosm pedal!"

AI Assistant Response: The AI interprets this complex musical request and creates a complete preset by:

Querying pedal capabilities - Gets LVX parameter mappings from MCP server
Translating musical concept - "Microcosm-style" → specific LVX parameters
Executing batch commands - Sends multiple MIDI CC commands in sequence
Real-time results - User hears preset being built, saves when satisfied

Technical Implementation:

Poly delay structure for granular-style processing (like Microcosm's multi-voice approach)
BBD engine for analog warmth and character
~600ms delay time for ambient textures
Granulize modulation in feedback loop for signature granular effects
Complex rhythmic timing (left=triplet quarter, right=dotted eighth)
Poly Chroma pitch shifting + State Variable filter for character
78% wet mix for ambient, texture-heavy sound

What You Hear: ✨ Granular texture and grain similar to Microcosm
🎵 Warm, analog-style repeats with subtle pitch shifting
🔊 Complex stereo field with cross-feedback
🌊 Filtered, ambient character perfect for pads and textures

This showcases the system's ability to interpret abstract musical concepts and translate them into precise hardware control!

🧪 Testing

Run the comprehensive test suite:

mvn test

25 focused tests covering:

✅ MIDI byte generation and validation
✅ Command execution with mock hardware
✅ End-to-end AI assistant → MCP server → pedal workflows
✅ Error handling and failure scenarios
✅ Batch command coordination

Test Examples

// AI generates command → MCP executes → Verifies MIDI bytes
testAIAssistantRequestsBrighterSound()
// Expected: B0 05 64 sent to hardware

// Multiple commands for complex sounds
testAIAssistantRequestsSlapbackDelay() 
// Expected: B0 03 23, B0 04 14, B0 01 1E sequence

🔧 Development

Project Structure

src/main/java/com/guyko/
├── models/          # Data models (PedalModel, MidiCommand, CCParameter)
├── midi/            # MIDI execution layer (executors, results)
├── persistence/     # JSON-based pedal storage
├── mcp/             # MCP server implementation  
└── pedals/          # Pre-configured pedal definitions

Adding New Pedals

Create parameter definitions with CC mappings
Use PedalRepository to save configurations
Test with MockMidiExecutor before hardware

Architecture Principles

AI Assistant: Natural language → MIDI commands (external)
MCP Server: Command validation → Hardware execution (this project)
Clean separation: No NLP in MCP server, no hardware details in AI

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-pedal)
Add your pedal configurations or improvements
Write tests for new functionality
Commit changes (git commit -m 'Add Amazing Pedal support')
Push to branch (git push origin feature/amazing-pedal)
Open a Pull Request

Development Setup

# Clone and build
git clone https://github.com/guyko/midimcp.git
cd midimcp
mvn compile

# Run tests
mvn test

# Start development server
mvn exec:java

📋 Roadmap

More Pedals - Add popular delay, reverb, overdrive pedals
MIDI Learn - Auto-discover CC mappings from pedals
Preset Management - Save/recall complete pedal settings
Real-time Monitoring - Live MIDI traffic visualization
Plugin Support - VST/AU plugin control via MIDI
Web Interface - Browser-based pedal control dashboard

❓ FAQ

Q: Does this work with any MIDI pedal?
A: Yes! Add your pedal's CC mappings using the add_pedal tool.

Q: Which AI assistants are supported?
A: Any MCP-compatible assistant (Claude, ChatGPT with MCP, etc.)

Q: Can I use this without real MIDI hardware?
A: Yes! Use MockMidiExecutor for testing and development.

Q: How do I add my pedal?
A: Check the Meris LVX example in MerisLVXLoader.kt and create similar mappings.

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🙏 Acknowledgments

Model Context Protocol for the excellent standard
Meris for detailed MIDI documentation
Guitar effects community for inspiration

🎸 Rock on with AI-controlled guitar effects! 🤖

⭐ Star this repo • 🐛 Report Bug • 💡 Request Feature

Name		Name	Last commit message	Last commit date
Latest commit History 38 Commits
.github		.github
data/pedals		data/pedals
docs		docs
src		src
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
pom.xml		pom.xml
run-server.sh		run-server.sh
start-mcp-server-jar.sh		start-mcp-server-jar.sh
start-mcp-server.sh		start-mcp-server.sh
start-mcp-wrapper.sh		start-mcp-wrapper.sh

Uh oh!

License

guyko/midimcp

Folders and files

Latest commit

History

Repository files navigation

🎸 MIDI Guitar Pedal MCP Server

🚀 What is this?

✨ Features

🏗️ Architecture

🚀 Quick Start

Prerequisites

1. Clone and Build

2. Run the MCP Server

3. Connect Your AI Assistant

Claude Desktop Integration

Other MCP-Compatible AI Assistants

🎵 Example Usage

Adding a New Pedal

Executing MIDI Commands

Batch Commands for Complex Sounds

Mercury X Reverb Control

Enzo X Synthesizer Control

Quad Cortex Scene Control

Preset Creation via CC Commands

How Preset Creation Works

LVX Delay Preset Creation

Mercury X Reverb Preset Creation

Enzo X Synthesizer Preset Creation

H90 Harmonizer Program Creation

🎛️ Included Pedals

Meris LVX Delay (Pre-loaded - MIDI Channel 2)

Meris Mercury X Reverb (Pre-loaded - MIDI Channel 1)

Meris Enzo X Synthesizer (Pre-loaded - MIDI Channel 3)

Neural DSP Quad Cortex (Pre-loaded - MIDI Channel 4)

Eventide H90 Harmonizer (Pre-loaded - MIDI Channel 8)

🎵 Real-World Example: Microcosm-Style LVX Preset

🧪 Testing

Test Examples

🔧 Development

Project Structure

Adding New Pedals

Architecture Principles

🤝 Contributing

Development Setup

📋 Roadmap

❓ FAQ

📄 License

🙏 Acknowledgments

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Sponsor this project

Uh oh!

Packages 0

Languages

Packages