halapenyoharry/linux-audio-mcp

Linux Audio MCP

Model Context Protocol servers for controlling Linux audio applications and session managers.

⚠️ UNDER DEVELOPMENT: This project is in early development and has not been fully tested. Use at your own risk. Contributions and testing help welcome!

Overview

This project provides MCP (Model Context Protocol) servers that enable AI assistants to control various Linux audio tools.

Compatible with:

• Claude Desktop (via config file)

• Claude Code (via MCP integration)

• Any MCP-compatible AI assistant

• RaySession - Audio session management (JACK/PipeWire)

• Agordejo (coming soon) - NSM session manager

• Carla (planned) - Plugin host control

• QjackCtl (planned) - JACK patchbay control

• PipeWire (planned) - Audio routing control

Features

Current

• ✅ RaySession Control
  • Session management (load, save, create)
  • Client control (start/stop/restart audio apps)
  • Snapshot management (backup/restore)
  • Template management
  • Full ray_control CLI integration

Planned

• 🚧 Agordejo/NSM control via OSC
• 🚧 Carla plugin parameter control
• 🚧 JACK routing management
• 🚧 PipeWire node control
• 🚧 MIDI mapping configuration

Installation

Prerequisites

# Python 3.8+
python3 --version

# pip (install if needed)
sudo apt install python3-pip

# MCP SDK
pip3 install --user mcp

# Audio tools (at least one)
which ray_control   # RaySession
which agordejo      # Agordejo
which carla         # Carla

Install MCP SDK

# Install the MCP Python SDK
pip3 install --user mcp

# Or install from requirements
pip3 install --user -r requirements.txt

Clone Repository

git clone https://github.com/creatdevz/linux-audio-mcp.git
cd linux-audio-mcp

Quick Start

1. Test the RaySession server

python3 src/servers/raysession_mcp.py

2. Configure Your AI Assistant

Add to your MCP-compatible AI assistant configuration (e.g., ~/.config/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "linux-audio": {
      "command": "python3",
      "args": ["/home/harold/Projects/linux-audio-mcp/src/main.py"]
    }
  }
}

3. Restart Your AI Assistant

Look for the connection indicator (e.g., 🔌 icon) showing MCP servers are connected.

4. Control your audio sessions

Ask your AI assistant:

• "Start RaySession and load my music session"
• "List all audio clients and restart the mixer"
• "Take a snapshot before making changes"
• "Show me the current session status"

Project Structure

linux-audio-mcp/
├── src/
│   ├── main.py                 # Main MCP server entry point
│   ├── servers/
│   │   ├── raysession_mcp.py   # RaySession control
│   │   ├── agordejo_mcp.py     # Agordejo control (planned)
│   │   └── carla_mcp.py        # Carla control (planned)
│   └── utils/
│       └── audio_utils.py      # Shared utilities
├── docs/
│   ├── ray_control_guide.md    # RaySession CLI reference
│   ├── architecture.md         # System architecture
│   └── pipewire-troubleshooting.md # PipeWire/PulseAudio fixes
├── examples/
│   └── claude_config.json      # Example Claude Desktop config
├── tests/
│   └── test_raysession.py      # Unit tests
├── requirements.txt            # Python dependencies
└── README.md                   # This file

Available Tools

RaySession Tools

Known Issues & Solutions

Carla GUI Not Showing

If Carla is running but window isn't visible:

# Restart the client
control_client('carla', 'stop')
time.sleep(1)
control_client('carla', 'start')
# Then show GUI
ray_control client carla show_optional_gui

Connection Management (No QjackCtl Needed!)

RaySession Patchbay

RaySession has its own patchbay that saves connections with the session:

# Connections are automatically saved when you save the session
ray_control save

# To prevent auto-connections from new apps:
# In RaySession GUI: Tools → Patchbay → Patchbay Exclusivity
# This stops new apps from making default connections

PipeWire Exclusive Mode

Prevent unwanted auto-connections system-wide:

# Create exclusive patchbay configuration
pw-jack -x  # Runs in exclusive mode - no auto-connections

# Or use WirePlumber rules for permanent exclusivity
# Edit ~/.config/wireplumber/main.lua.d/51-disable-autoconnect.lua

Connection Persistence Methods

1. RaySession (Recommended): Saves all connections in session
2. Carla Patchbay: Can save/load connection presets (.carxp files)
3. aj-snapshot: Command-line tool to save/restore JACK connections
4. PipeWire session manager: Built-in connection memory

You don't need QjackCtl! RaySession handles everything QjackCtl does, plus:

• Saves connections with session
• Manages client lifecycle
• Handles JACK through PipeWire automatically
• Has its own patchbay view (Tools → Patchbay)

Resources (Read-only)

Development

Adding New Audio Applications

1. Create a new server in src/servers/:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("app_name")

@mcp.tool()
def control_app(action: str) -> str:
    # Implementation
    pass

2. Register in src/main.py
3. Add documentation
4. Submit PR

Testing

# Run tests
python3 -m pytest tests/

# Test individual server
python3 src/servers/raysession_mcp.py

Roadmap

Phase 1: Session Managers (Current)

• RaySession support
• Agordejo/NSM support
• Session switching/templating

Phase 2: Audio Routing

• JACK patchbay control
• PipeWire node management
• MIDI routing

Phase 3: Plugin Control

• Carla plugin parameters
• LV2 plugin control
• Preset management

Phase 4: Advanced Features

• Real-time monitoring
• Audio analysis tools
• Recording control

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Submit a pull request

License

MIT License - See LICENSE file for details

Acknowledgments

• RaySession by Houston4444
• Model Context Protocol by Anthropic
• Linux audio community

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Author

Created by the creatdevz organization for the Linux audio community.

Bringing AI assistance to Linux audio production 🎵🤖