内容
<div align="center">
# 🎵 MusicMCP.AI MCP 服务器
**基于模型上下文协议的 AI 音乐生成**
MusicMCP.AI 官方模型上下文协议（MCP）服务器，能够与先进的 AI 音乐生成平台无缝交互。该服务器允许 MCP 客户端（如 Claude Desktop、OpenAI Agents 等）通过自然语言命令生成 AI 音乐。
</div>
## ✨ 功能特点
- **🎼 AI 音乐生成**: 根据文本提示使用 MusicMCP.AI 的最先进 AI 模型生成歌曲
- **🎵 双重生成模式**: 支持灵感模式和自定义模式
- **🔗 直接下载链接**: 获取生成的音乐的直接下载 URL
- **🎹 乐器选项**: 生成仅有乐器的音乐或带有歌词的完整歌曲
- **✅ API 密钥验证**: 检查您的 API 密钥有效性和剩余积分
- **🏥 健康监测**: 检查 API 服务健康状态
- **📊 API 信息**: 获取有关可用端点和成本的详细信息
## 🚀 使用 Claude Desktop 快速入门
1. **获取 API 密钥**: 从 [MusicMCP.AI 平台](https://www.musicmcp.ai) 获取您的 API 密钥
2. **安装 uv**: 使用 `curl -LsSf https://astral.sh/uv/install.sh | sh` 安装 Python 包管理器
3. **配置 Claude**: 进入 Claude > 设置 > 开发者 > 编辑配置 > claude_desktop_config.json 并添加：
```json
{
"mcpServers": {
"MusicMCP.AI": {
"command": "uvx",
"args": [
"aimusic-mcp"
],
"env": {
"MUSICMCP_API_KEY": "<insert-your-api-key-here>",
"MUSICMCP_API_URL": "https://www.musicmcp.ai/api",
"TIME_OUT_SECONDS": "600"
}
}
}
}
```
4. **重启 Claude**: 重启 Claude 应用，您将看到 **5 个 MCP 工具** 可用，指示加载成功
## ⚙️ 环境变量
| 变量名 | 描述 | 默认值 | 是否必需 |
|----------|-------------|---------|----------|
| `MUSICMCP_API_KEY` | 您的 MusicMCP.AI API 密钥 | - | ✅ 是 |
| `MUSICMCP_API_URL` | MusicMCP.AI API 基地址 | `https://www.musicmcp.ai/api` | ❌ 否 |
| `TIME_OUT_SECONDS` | 音乐生成的超时时间（秒） | `600` (10 分钟) | ❌ 否 |
## 🛠️ 可用工具
### 1. 🎼 生成提示歌曲（灵感模式）
根据简单的文本描述生成 AI 音乐。AI 自动创建标题、歌词和风格。
**费用**: 每次生成 5 个积分（创建 2 首歌曲）
**参数：**
- `prompt`（字符串）：音乐主题的简单描述（1-1200 个字符）
- `instrumental`（布尔值）：是否仅生成乐器音乐
- `style`（字符串，可选）：音乐风格（例如“ambient”，“pop”，“rock”）
**示例提示：**
```
"帮助我生成一首关于和平早晨的歌曲"
"想要一首表达思念的歌曲"
"为友谊创作音乐"
```
**输出示例：**
```
✅ 歌曲 1 生成成功！
📌 标题：和平早晨
🆔 ID：c7630638-b8ba-4984-876b-6dd7e6eeb796
🔗 下载 URL：https://cdn.musicmcp.ai/songs/abc123.mp3
🖼️ 封面图片：https://cdn.musicmcp.ai/images/abc123.jpg
⏱️ 时长：180s
🎵 风格标签：ambient，meditation，peaceful
🎹 乐器：否
📅 创建时间：2025-01-15T10:30:45.123Z
📝 歌词预览：
[第一节]
柔和的阳光充满房间
晨间露水和甜美的香水...
您可以从上面的 URL 下载或播放音频。
✅ 歌曲 2 生成成功！
📌 标题：早晨的和平
🆔 ID：d8741749-c9cb-5095-987c-7ee8f7ffb907
🔗 下载 URL：https://cdn.musicmcp.ai/songs/def456.mp3
🖼️ 封面图片：https://cdn.musicmcp.ai/images/def456.jpg
⏱️ 时长：213s
🎵 风格标签：ambient，meditation，peaceful
🎹 乐器：否
📅 创建时间：2025-01-15T10:30:45.126Z
📝 歌词预览：
[第一节]
宁静而安静，柔软而静止
和平的思想在山丘上...
您可以从上面的 URL 下载或播放音频。
```
### 2. 🎵 生成自定义歌曲（自定义模式）
使用您提供的特定歌词、标题和风格参数生成 AI 音乐。
**费用**: 每次生成 5 个积分（创建 2 首歌曲）
**参数：**
- `title`（字符串）：歌曲标题（必填）
- `instrumental`（布尔值）：是否仅生成乐器音乐（必填）
- `lyric`（字符串，可选）：完整的歌词内容（当 instrumental 为 true 时不需要）
- `tags`（字符串，可选）：音乐风格标签（例如“pop”，“rock”，“folk”）
**示例用法：**
```
请帮助我生成一首歌曲：
标题：夏日梦想
歌词：[完整的歌词内容]
风格：folk
或仅乐器：
标题：夏日微风
乐器：是
风格：ambient
```
**输出示例：**
```
✅ 自定义歌曲“夏日梦想”（版本 1）生成成功！
📌 标题：夏日梦想
🆔 ID：d1ed75a7-3e0b-42c6-b2be-7631204074fe
🔗 下载 URL：https://cdn.musicmcp.ai/songs/xyz789.mp3
🖼️ 封面图片：https://cdn.musicmcp.ai/images/xyz789.jpg
⏱️ 时长：195s
🎵 风格标签：folk，acoustic，summer
🎹 乐器：否
📅 创建时间：2025-01-15T11:45:30.456Z
📝 歌词预览：
[第一节]
走过夏日田野
金色小麦和自然的产量...
您可以从上面的 URL 下载或播放音频。
✅ 自定义歌曲“夏日梦想”（版本 2）生成成功！
📌 标题：夏日梦想
🆔 ID：e2fe86b8-4f1c-53d7-c3cf-8742305185gf
🔗 下载 URL：https://cdn.musicmcp.ai/songs/uvw012.mp3
🖼️ 封面图片：https://cdn.musicmcp.ai/images/uvw012.jpg
⏱️ 时长：203s
🎵 风格标签：folk，acoustic，summer
🎹 乐器：否
📅 创建时间：2025-01-15T11:45:30.459Z
📝 歌词预览：
[第一节]
走过夏日田野
金色小麦和自然的产量...
您可以从上面的 URL 下载或播放音频。
```
### 3. ✅ 验证 API 密钥
检查您的 API 密钥是否有效并查看剩余积分。
**费用**: 免费
**示例用法：**
```
"验证我的 API 密钥"
"检查我的积分余额"
```
### 4. 🏥 检查 API 健康状态
监控 MusicMCP.AI API 服务的健康状态。
**费用**: 免费
**示例用法：**
```
"检查 API 服务状态"
```
### 5. 📊 获取 API 信息
获取有关 API 的详细信息，包括速率限制和文档。
**费用**: 免费
**示例用法：**
```
"获取 API 信息"
```
## 💰 积分与定价
| 操作 | 积分成本 | 输出 |
|-----------|-------------|--------|
| 生成灵感音乐 | 5 积分 | 2 首歌曲 |
| 生成自定义音乐 | 5 积分 | 2 首歌曲 |
| 查询音乐状态 | 0 积分（免费） | - |
| 验证 API 密钥 | 0 积分（免费） | - |
| API 健康检查 | 0 积分（免费） | - |
| 获取 API 信息 | 0 积分（免费） | - |
## 💡 示例用法
⚠️ **注意**: 使用音乐生成工具需要 MusicMCP.AI 积分。
### 尝试使用 Claude：
#### **灵感模式：**
- "请帮助我生成一首关于和平早晨的歌曲"
- "想要一首表达思念的歌曲"
- "为友谊创作音乐"
- "生成一份环境音乐曲目"
#### **自定义模式：**
- "请帮助我生成一首歌曲，标题：夏日梦想，歌词：[完整歌词]，风格：folk"
- "创建一首歌曲，标题：春日承诺，歌词：[完整歌词]，Pop 风格"
- "生成一首乐器歌曲，标题：海洋微风，风格：ambient"
#### **管理功能：**
- "验证我的 API 密钥"
- "检查我还剩多少积分"
- "检查 API 服务状态"
## 📦 安装
### 使用 uv（推荐）
```bash
uvx aimusic-mcp
```
### 使用 pip
```bash
pip install aimusic-mcp
```
### 从源码
```bash
git clone https://github.com/ai-music-repo/aimusic-mcp-tool.git
cd aimusic-mcp-tool
pip install -e .
```
### 快速安装脚本
```bash
chmod +x install.sh
./install.sh
```
## 🔌 API 集成
该 MCP 服务器与 MusicMCP.AI 的 RESTful API 集成：
- **`POST /music/generate/inspiration`**: 创建音乐生成任务（灵感模式）
- **`POST /music/generate/custom`**: 创建自定义音乐生成任务
- **`POST /music/generate/query`**: 查询音乐状态（支持批量查询）
- **`POST /validate`**: 验证 API 密钥并检查积分
- **`GET /health`**: 检查 API 服务健康状态
- **`GET /info`**: 获取 API 信息
### 🔄 异步 API 工作流程
音乐生成是 **异步的**。MCP 服务器自动处理：
**步骤 1：提交生成请求**
```bash
POST /music/generate/inspiration 或 /music/generate/custom
→ 返回：{"code": 200, "data": {"ids": ["id1", "id2"]}}
```
**步骤 2：自动轮询（由 MCP 内部处理）**
```bash
POST /music/generate/query with {"ids": ["id1", "id2"]}
→ 每 2 秒轮询一次，直到状态 = 1（完成）
→ 歌曲状态：0 = 失败，1 = 完成，2 = 进行中
```
**步骤 3：返回完整的歌曲信息**
```
当所有歌曲完成后，返回完整详细信息：
- songName，songUrl，imgUrl，duration，tags 等。
```
**幕后：**
1. 用户调用 `generate_prompt_song()` 或 `generate_custom_song()`
2. MCP 发送生成请求 → 接收 2 个歌曲 ID
3. MCP 自动每 2 秒轮询 `/music/generate/query`
4. 当所有歌曲完成（状态 = 1）时，返回下载 URL
5. 默认超时时间：10 分钟（可通过 `TIME_OUT_SECONDS` 配置）
**重要注意事项：**
- ⏱️ 生成通常需要 2-5 分钟每首歌曲
- 🔁 MCP 服务器自动处理所有轮询
- 🎵 每次生成始终创建 2 个歌曲变体
- 💰 生成请求成功时扣除积分（5）
- ⚠️ 如果生成失败，不扣除积分
## 🐛 故障排除
### 常见问题
1. **API 密钥错误**: 确保 `MUSICMCP_API_KEY` 设置正确
- 使用 `validate_api_key` 工具检查您的密钥
2. **积分不足（402 错误）**: 您没有足够的积分
- 在 https://www.musicmcp.ai 检查您的余额
- 充值您的账户
3. **超时错误**: 如果音乐生成时间较长，请增加 `TIME_OUT_SECONDS`
### 日志
在与 Claude Desktop 运行时，日志位于：
- **Windows**: `%APPDATA%\Claude\logs\mcp-server-MusicMCP.AI.log`
- **macOS**: `~/Library/Logs/Claude/mcp-server-MusicMCP.AI.log`
## 🧪 开发
### 运行测试
```bash
pytest tests/
```
### 本地开发
```bash
python -m musicmcp_ai_mcp.api
```
### 代码结构
```
musicmcp_ai_mcp/
├── __init__.py # 包初始化
├── __main__.py # CLI 入口点
└── api.py # 核心 MCP 服务器实现（430 行）
```
## 🔗 链接
- **平台**: https://www.musicmcp.ai
- **文档**: https://www.musicmcp.ai/docs
- **GitHub**: https://github.com/ai-music-repo/aimusic-mcp-tool
- **问题**: https://github.com/ai-music-repo/aimusic-mcp-tool/issues
## 📄 许可证
该项目在 MIT 许可证下许可 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。
---
<div align="center">
**由 MusicMCP.AI 团队用 ❤️ 制作**
*用 AI 将您的想法转化为音乐*
