内容
# renoise-mcp
用于通过OSC控制Renoise的MCP服务器。让Claude通过编写模式、触发音符和控制播放来创作音乐。
## 需求
- [Renoise](https://www.renoise.com/)（演示版或完整版）
- Python 3.11+
- [uv](https://docs.astral.sh/uv/)（推荐）或pip
## 安装
```bash
cd osc-mcp
uv sync
```
或使用pip：
```bash
pip install -e .
```
## Renoise 设置
1. 打开Renoise
2. 进入 `编辑 > 首选项 > OSC`
3. 启用OSC服务器
4. 将协议设置为UDP
5. 将端口设置为8000（或通过环境变量配置）
## Claude 代码配置
在您的 `~/.claude.json` 或 Claude Desktop MCP 设置中添加：
```json
{
"mcpServers": {
"renoise": {
"command": "uv",
"args": ["--directory", "/path/to/osc-mcp", "run", "renoise-mcp"],
"env": {
"RENOISE_HOST": "127.0.0.1",
"RENOISE_PORT": "8000"
}
}
}
}
```
## 工具
### 传输
- `play()` - 开始播放
- `stop()` - 停止播放
- `panic()` - 立即停止所有声音
- `set_bpm(bpm)` - 设置节奏（20-999）
- `set_lpb(lpb)` - 设置每拍行数
### 音符操作
- `trigger_note(instrument, note, velocity, track)` - 播放音符（实时，非记录）
- `stop_note(instrument, note, track)` - 停止触发的音符
- `set_note(pattern, track, line, note, instrument, volume, column)` - 在模式中写入音符
- `set_effect(pattern, track, line, effect, value, column)` - 写入效果命令
### 音轨控制
- `mute_track(track, muted)` - 静音/取消静音音轨
- `solo_track(track, soloed)` - 独奏/取消独奏音轨
- `set_track_volume(track, volume)` - 设置音轨音量（0-1）
### 模式操作
- `clear_pattern(pattern)` - 清除模式中的所有数据
- `set_pattern_length(pattern, lines)` - 设置模式长度（1-512）
- `jump_to_pattern(position)` - 跳转到序列位置
- `schedule_pattern(position)` - 调度下一个模式
### 高级创作
- `generate_breakbeat(pattern, track, style, lines, bpm, instrument, intensity, variation, add_chops)` - 生成breakbeat模式
- `generate_bass_pattern(pattern, track, root_note, scale, lines, instrument, density)` - 生成贝斯线
- `add_drum_fill(pattern, track, start_line, length, instrument, intensity)` - 添加鼓点填充
### 强大工具
- `evaluate_lua(code)` - 在Renoise中执行任意Lua代码
## 使用示例
### 基础：设置一个174 BPM的dnb音轨
```
set_bpm(174)
set_lpb(4)
set_pattern_length(0, 64)
```
### 生成amen风格的break
```
generate_breakbeat(
pattern=0,
track=0,
style="amen",
bpm=174,
intensity=0.8,
variation=0.3
)
```
### 生成贝斯线
```
generate_bass_pattern(
pattern=0,
track=1,
root_note=36, # C2
scale="minor_pentatonic",
density=0.6
)
```
### 手动音符放置
```
# Kick on beat 1
set_note(pattern=0, track=0, line=0, note=36, instrument=0)
# Snare on beat 2
set_note(pattern=0, track=0, line=4, note=38, instrument=0)
# Add sample offset effect
set_effect(pattern=0, track=0, line=8, effect="09", value=64)
```
### 直接Lua进行高级操作
```
evaluate_lua("""
local song = renoise.song()
song:pattern(1):track(1):line(1):note_column(1).note_value = 48
""")
```
## Break样式
- `amen` - 经典amen break模式，带有幽灵音符
- `two_step` - Syncopated two-step dnb模式
- `think` - Think break风格，带有特征性的syncopation
- `straight` - Four-on-floor影响的模式
## 音阶
- `minor` - 自然小调
- `minor_pentatonic` - 小调五声音阶（非常适合dnb贝斯）
- `dorian` - 多里安调式
- `phrygian` - 弗里吉亚调式（黑暗，中东风格）
- `major` - 大调
## 效果命令参考
常见的Renoise效果命令：
- `09xx` - 样本偏移（xx = 位置，00-FF）
- `0Rxy` - 重触发（x = 音量变化，y = 速度）
- `0Qxx` - 将音符延迟xx个ticks
- `0Dxx` - 音高下滑
- `0Uxx` - 音高上滑
- `0Bxx` - 播放样本反向
- `0Yxx` - 概率（xx%几率播放）
## 架构
```
Claude 代码
│
│ MCP 协议
▼
renoise-mcp 服务器（Python）
│
│ OSC（UDP）
▼
Renoise
```
服务器将MCP工具调用转换为Renoise理解的OSC消息。复杂的运算使用 `/renoise/evaluate` 端点直接在Renoise中运行Lua代码。
## 开发
```bash
# 安装开发依赖
uv sync --extra dev
# 运行测试
uv run pytest
# 格式化/检查
uv run ruff check --fix
uv run ruff format
```
## 许可证
MIT
