Linux Audio MCP

Linux音频MCP

用于控制Linux音频应用程序和会话管理器的模型上下文协议服务器。

⚠️ 开发中：该项目处于早期开发阶段，尚未经过全面测试。使用风险自负。贡献和测试帮助欢迎！

概述

该项目提供MCP（模型上下文协议）服务器，使AI助手能够控制各种Linux音频工具。

兼容：

• Claude桌面（通过配置文件）

• 克劳德代码（通过MCP集成）

• 任何兼容MCP的AI助手

• RaySession -音频会话管理（JACK/PipeWire）

• 配置 *（即将推出）* -NSM会话管理器

• 卡拉 *（计划中）* -插件主机控制

• QjackCtl *（计划中）* -JACK花篮控制

• PipeWire *（计划中）* -音频路由控制

特性

当前

• ✅ RaySession控制

- 会话管理（加载、保存、创建） - 客户端控制（启动/停止/重新启动音频应用程序） - 快照管理（备份/恢复） - 模板管理 - 完整的ray_control CLI集成

计划的

• 🚧 通过OSC进行Agordejo/NSM控制
• 🚧 Carla插件参数控制
• 🚧 JACK路由管理
• 🚧 PipeWire节点控制
• 🚧 MIDI映射配置

安装

先决条件

# 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

安装MCP SDK

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

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

克隆存储库

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

快速开始

1.测试RaySession服务器

python3 src/servers/raysession_mcp.py

2.配置您的AI助手

添加到您的MCP兼容AI助手配置中（例如。， ~/.config/Claude/claude_desktop_config.json):

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

3.重新启动您的AI助手

查找连接指示符（例如。，🔌 图标）显示MCP服务器已连接。

4.控制您的音频会话

问你的AI助手：

• “启动RaySession并加载我的音乐会话”
• “列出所有音频客户端并重新启动混音器”
• “在进行更改之前拍摄快照”
• “显示当前会话状态”

项目结构

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

可用工具

RaySession工具

已知问题和解决方案

Carla GUI未显示

若卡拉正在跑步，但窗口不可见：

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

连接管理（无需QjackCtl！）

RaySession Patchbay

RaySession有自己的配线架，可以保存与会话的连接：

# 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专用模式

防止系统范围内不必要的自动连接：

# 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

连接持久化方法

1. RaySession（推荐）：保存会话中的所有连接
2. 卡拉·帕奇贝：可以保存/加载连接预设（.carxp文件）
3. i-快照：保存/恢复JACK连接的命令行工具
4. PipeWire会话管理器：内置连接存储器

你不需要QjackCtl！ RaySession处理QjackCtl所做的一切，此外：

• 保存与会话的连接
• 管理客户端生命周期
• 通过PipeWire自动处理JACK
• 有自己的配线架视图（工具→ Patchbay）

资源（只读）

发展

添加新的音频应用程序

1. 在中创建新服务器 src/servers/:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("app_name")

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

1. 注册 src/main.py
2. 添加文档
3. 提交PR

测试

# Run tests
python3 -m pytest tests/

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

路线图

第一阶段：会议经理（现任）

• \[x\] RaySession支持
• \[\]Agordejo/NSM支持
• \[\]会话切换/模板

第2阶段：音频路由

• \[\]JACK花篮控制
• \[\]PipeWire节点管理
• \[\]MIDI路由

阶段3：插件控制

• \[\]Carla插件参数
• \[\]LV2插件控制
• \[\]预设管理

第四阶段：高级功能

• \[\]实时监控
• \[\]音频分析工具
• \[\]录音控制

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支
3. 为新功能添加测试
4. 提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件

致谢

• RaySession by休斯顿4444
• 模型上下文协议 通过Anthropic
• Linux音频社区

支持

• 问题:
• 讨论:

作者

创建者： creatdevz Linux音频社区组织。

______________________________________________________________________

*为Linux音频制作提供人工智能辅助* 🎵🤖