金大哥 - aimusic-mcp-tool MCP 详情

article

README

🚀 🎵 MusicMCP.AI MCP Server

MusicMCP.AI MCP Server 是官方的模型上下文协议（MCP）服务器，可实现与先进的 AI 音乐生成平台的无缝交互。该服务器允许像 Claude Desktop、OpenAI Agents 等 MCP 客户端通过自然语言命令生成 AI 音乐。

✨ 主要特性

🎼 AI 音乐生成：使用 MusicMCP.AI 的先进 AI 模型，根据文本提示生成歌曲。
🎵 双生成模式：支持灵感模式和自定义模式。
🔗 直接下载链接：获取生成音乐的直接下载 URL。
🎹 乐器选项：可生成纯乐器音乐或带人声的完整歌曲。
✅ 信用余额检查：检查 API 密钥的有效性和剩余信用额度。
🏥 健康监测：检查 API 服务的健康状态。

🚀 快速开始

使用 Claude Desktop 快速上手

获取 API 密钥：从 MusicMCP.AI 平台获取 API 密钥。
安装 uv：使用以下命令安装 Python 包管理器：

curl -LsSf https://astral.sh/uv/install.sh | sh

配置 Claude：进入 Claude > 设置 > 开发者 > 编辑配置 > claude_desktop_config.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"
            }
        }
    }
}

重启 Claude：重启 Claude 应用程序，你将看到 4 个 MCP 工具 可用，这表明加载成功。

⚙️ 环境变量

| 属性 | 详情 | |------|------| | 变量 | 描述 | 默认值 | 是否必需 | | MUSICMCP_API_KEY | 你的 MusicMCP.AI API 密钥 | - | ✅ 是 | | MUSICMCP_API_URL | MusicMCP.AI API 基础 URL | https://www.musicmcp.ai/api | ❌ 否 | | TIME_OUT_SECONDS | 音乐生成的超时时间（秒） | 600（10 分钟） | ❌ 否 |

🛠️ 可用工具

1. 🎼 生成提示歌曲（灵感模式）

根据简单的文本描述生成 AI 音乐。AI 会自动创建标题、歌词和风格。

费用：每次生成 5 个信用点（生成 2 首歌曲）
参数：
- prompt (str)：音乐主题的简单描述（1 - 1200 个字符）
- instrumental (bool)：是否仅生成纯乐器音乐
- style (str, 可选)：音乐风格（例如，"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
⏱️ 时长: 180 秒
🎵 风格标签: 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
⏱️ 时长: 213 秒
🎵 风格标签: ambient, meditation, peaceful
🎹 纯乐器: 否
📅 创建时间: 2025-01-15T10:30:45.126Z
📝 歌词:
[主歌]
平静而安静，柔和而静止
山上宁静的思绪
周围是大自然的美丽
温柔的低语，舒缓的声音

你可以从上述 URL 下载或播放音频。

2. 🎵 生成自定义歌曲（自定义模式）

根据你提供的特定歌词、标题和风格参数生成 AI 音乐。

费用：每次生成 5 个信用点（生成 2 首歌曲）
参数：
- title (str)：歌曲标题（必需）
- instrumental (bool)：是否仅生成纯乐器音乐（必需）
- lyric (str, 可选)：完整的歌词内容（当 instrumental 为 true 时不需要）
- tags (str, 可选)：音乐风格标签（例如，'pop'、'rock'、'folk'）
示例用法：

请帮我生成一首歌曲：
标题: 夏日梦想
歌词: [完整歌词内容]
风格: 民谣

或者对于纯乐器歌曲：
标题: 夏日微风
纯乐器: 是
风格: 氛围音乐

输出示例：

✅ 自定义歌曲 '夏日梦想'（版本 1）生成成功！

📌 标题: 夏日梦想
🆔 ID: d1ed75a7-3e0b-42c6-b2be-7631204074fe
🔗 下载 URL: https://cdn.musicmcp.ai/songs/xyz789.mp3
🖼️ 封面图片: https://cdn.musicmcp.ai/images/xyz789.jpg
⏱️ 时长: 195 秒
🎵 风格标签: 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
⏱️ 时长: 203 秒
🎵 风格标签: folk, acoustic, summer
🎹 纯乐器: 否
📅 创建时间: 2025-01-15T11:45:30.459Z
📝 歌词:
[主歌]
漫步在夏日的田野
金色的小麦和大自然的馈赠
阳光在我脸上舞动
夏日温暖而甜蜜的拥抱

你可以从上述 URL 下载或播放音频。

3. ✅ 检查信用余额

检查你的 API 密钥是否有效，并查看剩余的信用点。

费用：免费
示例用法：

"检查我的信用余额"
"我还剩下多少信用点？"

4. 🏥 检查 API 健康状态

监控 MusicMCP.AI API 服务的健康状态。

费用：免费
示例用法：

"检查 API 服务状态"

💰 信用点与定价

| 操作 | 信用点成本 | 输出 | |-----------|-------------|--------| | 生成灵感音乐 | 5 个信用点 | 2 首歌曲 | | 生成自定义音乐 | 5 个信用点 | 2 首歌曲 | | 查询音乐状态 | 0 个信用点（免费） | - | | 检查信用余额 | 0 个信用点（免费） | - | | API 健康检查 | 0 个信用点（免费） | - |

💻 使用示例

基础用法

⚠️ 重要提示

使用音乐生成工具需要 MusicMCP.AI 信用点。

你可以尝试向 Claude 提问：

灵感模式：

"请帮我生成一首关于宁静早晨的歌曲"
"想要一首表达思念的歌曲"
"创作一首关于友谊的音乐"
"生成一首氛围音乐曲目"

自定义模式：

"请帮我生成一首歌曲，标题：夏日梦想，歌词：[完整歌词]，风格：民谣"
"创作一首歌曲，标题：春天的承诺，歌词：[完整歌词]，流行风格"
"生成一首纯乐器歌曲，标题：海风，风格：氛围音乐"

管理功能：

"检查我的信用余额"
"我还剩下多少信用点？"
"检查 API 服务状态"

📦 安装

使用 uv（推荐）

uvx aimusic-mcp

使用 pip

pip install aimusic-mcp

🔌 API 集成

此 MCP 服务器与 MusicMCP.AI 的 RESTful API 集成：

POST /music/generate/inspiration：创建音乐生成任务（灵感模式）
POST /music/generate/custom：创建自定义音乐生成任务
POST /music/generate/query：查询音乐状态（支持批量查询）
GET /credit：检查信用余额
GET /health：检查 API 服务健康状态

🔄 异步 API 工作流程

音乐生成是 异步的。MCP 服务器会自动处理此过程：

步骤 1：提交生成请求

POST /music/generate/inspiration 或 /music/generate/custom
→ 返回: {"code": 200, "data": {"ids": ["id1", "id2"]}}

步骤 2：自动轮询（由 MCP 内部处理）

POST /music/generate/query 并携带 {"ids": ["id1", "id2"]}
→ 每 2 秒轮询一次，直到状态 = 1（完成）
→ 歌曲状态：0 = 失败，1 = 完成，2 = 进行中

步骤 3：返回完整歌曲信息

一旦所有歌曲完成，返回完整详细信息：
- 歌曲名称、歌曲 URL、图片 URL、时长、标签等。

幕后流程：

用户调用 generate_prompt_song() 或 generate_custom_song()
MCP 发送生成请求 → 接收 2 个歌曲 ID
MCP 每 2 秒自动轮询 /music/generate/query
当所有歌曲完成（状态 = 1）时，返回下载 URL
默认超时时间：10 分钟（可通过 TIME_OUT_SECONDS 配置）

重要注意事项：

⏱️ 每首歌曲的生成通常需要 2 - 5 分钟
🔁 MCP 服务器会自动处理所有轮询
🎵 每次生成总是创建 2 个歌曲变体
💰 生成请求成功时扣除 5 个信用点
⚠️ 如果生成失败，不会消耗信用点

🐛 故障排除

常见问题

API 密钥错误：确保 MUSICMCP_API_KEY 设置正确。
- 使用 check_credit_balance 工具检查你的密钥。
信用点不足（402 错误）：你的信用点不足。
- 在 https://www.musicmcp.ai 上检查你的余额。
- 为你的账户充值。
超时错误：如果音乐生成时间较长，请增加 TIME_OUT_SECONDS。

日志

当与 Claude Desktop 一起运行时，日志可以在以下位置找到：

Windows：%APPDATA%\Claude\logs\mcp-server-MusicMCP.AI.log
macOS：~/Library/Logs/Claude/mcp-server-MusicMCP.AI.log

🧪 开发

运行测试

pytest tests/

本地开发

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
支持：support@musicmcp.ai

📄 许可证

本项目采用 MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件。

由 MusicMCP.AI 团队用心打造 ❤️

用 AI 将你的想法转化为音乐

aimusic-mcp-tool