内容
# Sonilo MCP 服务器
MCP（模型上下文协议）服务器，暴露 [Sonilo](https://platform.sonilo.com) 的 AI 音乐生成 API 给兼容 MCP 的客户端（Claude Desktop，Codex）。
### 音频播放依赖
`play_audio` 工具在运行时需要 PortAudio（用于 `sounddevice`）。在 macOS/Linux 上，通过以下方式安装：
- **macOS**：`brew install portaudio`
- **Debian/Ubuntu**：`sudo apt-get install libportaudio2`
`uvx sonilo-mcp` 和 `pip install` 将拉取 Python 绑定，但系统 PortAudio 库必须单独安装。其他工具（`text_to_music`、`video_to_music`、`get_account_services`、`get_usage`）无需 PortAudio 即可工作。
## 使用 Claude Desktop 快速入门
1. **获取您的 API 密钥**，从 [Sonilo 仪表板](https://platform.sonilo.com/dashboard/api-keys) 获取。
2. **安装 `uv` 包管理器**（提供 `uvx`）：
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
查看 [uv 仓库](https://github.com/astral-sh/uv) 获取其他安装方法。
3. **进入 Claude > 设置 > 开发者 > 编辑配置 > claude_desktop_config.json，并添加以下内容：**
```json
{
"mcpServers": {
"sonilo": {
"command": "uvx",
"args": ["sonilo-mcp"],
"env": {
"SONILO_API_KEY": "sks_...",
"SONILO_API_URL": "https://api.sonilo.com",
"TIME_OUT_SECONDS": "600"
}
}
}
}
```
4. **重启 Claude Desktop**。您应该会在工具菜单中看到 Sonilo 工具。
## 使用 Codex 快速入门
1. **获取您的 API 密钥**，从 [Sonilo 仪表板](https://platform.sonilo.com/dashboard/api-keys) 获取。
2. **安装 `uv` 包管理器**（提供 `uvx`）：
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
3. **进入 Codex > 设置 > MCP 服务器，并填写以下内容：**
或者，您可以将服务器添加到 `~/.codex/config.toml`:
```toml
[mcp_servers.sonilo]
command = "uvx"
args = ["sonilo-mcp"]
[mcp_servers.sonilo.env]
SONILO_API_KEY = "sk_..."
SONILO_API_URL = "https://api.sonilo.com"
TIME_OUT_SECONDS = "600"
```
4. **重启 Codex**（或启动新会话），然后运行 `/mcp` 以确认 `sonilo` 已连接并且其工具已列出。
## 示例用法
一旦服务器连接成功，只需用自然语言询问您的助手。例如：
- *"使用 Sonilo mcp 生成 30 秒的轻快 Lo-Fi 嘻哈音乐用于学习播放列表，并保存到我的桌面。"*
- *"使用 Sonilo 编写一段史诗般的管弦乐电影配乐，大约 60 秒长。"*
- *"制作与此视频匹配的背景音乐：`~/Desktop/promo.mp4`。"*
- *"为 `https://example.com/clip.mp4` 创作音乐，采用平静、氛围感的风格。"*
- *"我的账户有哪些 Sonilo 服务和限制？"*
- *"显示过去 7 天的 Sonilo 使用情况。"*
- *"播放您刚刚生成的音轨。"*
助手将调用匹配的工具（`text_to_music`、`video_to_music`、`get_account_services`、`get_usage` 或 `play_audio`），并将生成的音频保存到您配置的输出目录。
## 配置
### 环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
| `SONILO_API_KEY` | _（必填）_ | Bearer 令牌。 |
| `SONILO_API_URL` | `https://api.sonilo.com` | 公共 API 基本 URL。 |
| `SONILO_MCP_BASE_PATH` | `~/Desktop` | 默认输出目录和相对输入路径的基本路径。同时也是隔离边界（见下文）。 |
| `SONILO_MCP_ALLOW_ANY_PATH` | `false` | 设置为 `true` 以允许工具在 `SONILO_MCP_BASE_PATH` 外读写文件。 |
| `TIME_OUT_SECONDS` | `600` | 生成超时，单位为秒。与后端读取超时对齐。 |
### 文件访问和隔离
默认情况下，文件工具（`video_to_music` 输入、`play_audio` 和任何 `output_directory`）**被隔离到 `SONILO_MCP_BASE_PATH`**。解析后超出该路径的文件路径（在符号链接解析后）将被拒绝。这限制了客户端被诱骗读取或泄露任意文件的风险。要选择退出 - 例如，从磁盘的其他位置读取视频 - 请设置 `SONILO_MCP_ALLOW_ANY_PATH=true`。
## 工具
| 工具 | 描述 | 费用 |
|---|---|---|
| `text_to_music(prompt, duration, output_directory?)` | 从文本提示生成音乐。 | ✅ |
| `video_to_music(video_path? \| video_url?, prompt?, output_directory?)` | 生成与视频匹配的音乐。最大时长 **360s（6 分钟）**；受账户上传大小限制（通常为 300 MB）。 | ✅ |
| `get_account_services()` | 列出可用服务和限制。 | ❌ |
| `get_usage(days=30)` | 显示使用情况总结 + 每天的明细。 | ❌ |
| `play_audio(input_file_path)` | 播放本地音频文件。 | ❌ |
标记为 ✅ 的工具会调用 API，从而产生 Sonilo 账户费用。
> **可选：** 如果安装了 [`ffprobe`](https://ffmpeg.org/)（FFmpeg 的一部分），`video_to_music` 会在上传前本地检查视频时长并拒绝超过 360 秒的视频。否则，后端仍会强制执行相同的限制。
## 输出格式
生成的音频保存为 `.m4a`（MP4 容器中的 AAC - 这是后端当前输出的格式）。文件名使用后端返回的标题（转换为 slug）或 `sonilo-<timestamp>.m4a` 备用。 当返回多个并行流时，会追加 `-<index>` 后缀。
## 常见错误
| 消息 | 操作 |
|---|---|
| `Invalid SONILO_API_KEY` | 在 <https://platform.sonilo.com/dashboard/api-keys> 验证密钥。 |
| `Insufficient minutes` / `Credit limit exceeded` | 在 <https://platform.sonilo.com/dashboard/billing> 充值。 |
| `Rate limit exceeded` | 检查 `get_account_services` 获取您的 rpm/并发限制。 |
| `Generation timed out` | 提高 `TIME_OUT_SECONDS`。检查 `get_usage` 以确认后端是否已完成并计费。 |
