MCP MeloTTS 语音生成器 (MCP MeloTTS Audio Generator)

本项目是一个 Model Context Protocol (MCP) 服务器，为 AI 助手提供将文本生成语音音频的能力，基于 MeloTTS。

支持自动将长文本按标点与长度分割为不超过 100 字的小段，逐段生成 WAV 文件，并使用 ffmpeg 无损拼接为完整音频。

✨ 功能特性

• 文本转语音：使用 MeloTTS 将文本生成高质量语音
• 自动分段：长文本自动分段，避免一次过长导致失败
• 无损拼接：使用 ffmpeg 将分段 WAV 拼接为完整文件
• 可配置语速、语言、设备与说话人
• 跨平台：Windows、Linux、macOS

🚀 安装

使用 uvx (推荐)

docker run -d -p 127.0.0.1:9900:8888 kisaragi29/melotts:latest
uvx mcp-melotts@latest

使用 pip

pip install mcp-melotts@latest

从源码安装

git clone https://github.com/aardpro/mcp-melotts.git
cd mcp-melotts
pip install -e .

⚙️ 配置

配置

前置条件

开发电脑已安装并可用：

• ffmpeg（用于拼接音频）
• MeloTTS（可通过本地 Python 包 melo.api 或 Docker Gradio 服务）

启动前检查

启用 MCP 时会自动检查以下条件：

• 本机 9900 端口是否启动了 MeloTTS HTTP 服务（用于 HTTP 模式）
• 系统是否可调用 ffmpeg（用于无损拼接） 任一不满足将抛出错误并终止启动

配置文件

内置配置文件位于 src/main/config.json，可设置：

• defaultLanguage：默认语言代码（ZH/EN/JP/ES）
• defaultSpeed：默认语速
• defaultDevice：默认设备（cpu 或 cuda:0）
• defaultSpeaker：默认说话人标签
• chunkSizeLimit：分段长度上限（推荐 100）

MCP 客户端配置

将以下内容添加到你的 MCP 客户端配置中（例如 Claude Desktop, Cursor）：

选项 1: 使用 uvx

{
  "mcpServers": {
    "McpMeloTTS": {
      "command": "uvx",
      "args": ["mcp-melotts"]
    }
  }
}

选项 2: 使用 pip

{
  "mcpServers": {
    "McpMeloTTS": {
      "command": "mcp-melotts"
    }
  }
}

选项 3: Windows 系统

{
  "mcpServers": {
    "McpMeloTTS": {
      "command": "cmd",
      "args": [
        "/c",
        "chcp 65001 >nul && uvx mcp-melotts"
      ]
    }
  }
}

选项 4: Linux/macOS：

{
  "mcpServers": {
    "McpMeloTTS": {
      "command": "python",
      "args": ["-m", "main"]
    }
  }
}

🛠️ 可用工具

mcp_melotts_generate_audio

将文本生成语音文件。适用于“根据文本生成音频文件”等请求。支持自动分段与 ffmpeg 无损拼接，支持两种调用模式：本地 melo.api 与 Docker Gradio HTTP 接口。

参数:

• text (string, 必填): 要转换为语音的文本
• language (string, 可选): 语言代码（默认 ZH）
• speaker (string, 可选): 说话人标签（默认 ZH）
• speed (number, 可选): 语速（默认 1.0）
• device (string, 可选): cpu 或 cuda:0（默认 cpu）
• split_sentences (boolean, 可选): 是否自动分段（默认 true）
• output_dir (string, 必填): 输出目录
• target_filename (string, 可选): 最终输出文件名，默认时间戳命名
• use_http_api (boolean, 可选): 是否使用 Docker Gradio HTTP 接口（默认 false）
• api_base_url (string, 可选): HTTP 接口基础地址（如 http://localhost:9900）
• fn_index (number, 可选): Gradio 函数索引（默认 1）
• session_hash (string, 可选): Gradio 会话哈希（不提供则自动生成）

调用示例（本地 melo.api 模式）:

{
  "name": "mcp_melotts_generate_audio",
  "arguments": {
    "text": "我最近在学习machine learning，希望能够在未来的artificial intelligence领域有所建树。",
    "language": "ZH",
    "speaker": "ZH",
    "speed": 1.0,
    "output_dir": "./audio"
  }
}

调用示例（Docker Gradio HTTP 模式）:

{
  "name": "mcp_melotts_generate_audio",
  "arguments": {
    "text": "请将以下内容朗读为音频……",
    "language": "ZH",
    "speed": 1.0,
    "output_dir": "./audio",
    "use_http_api": true,
    "api_base_url": "http://localhost:9900",
    "fn_index": 1
  }
}

说明：HTTP 模式需要先运行 Docker 容器并开放 9900 端口，脚本会通过 /queue/join 与 /queue/data 监听生成进度并下载音频。

⚡ 快速开始

使用虚拟环境运行

python -m venv .venv
.venv/Scripts/python.exe -m pip install -U pip
.venv/Scripts/pip.exe install -r requirements.txt
.venv/Scripts/python.exe -m main

一键启动（Windows）

双击或执行项目根目录的 start_server.bat，它会自动创建 .venv、安装依赖并在虚拟环境中启动 MCP。

生成音频的测试脚本

.venv/Scripts/python.exe test-generate-audio.py --input test-text.txt --output-dir output --use-http-api --api-base-url http://localhost:9900

打印的路径即生成的 wav 文件（如 output/1767514828_93829.wav）。

💡 使用示例

配置完成后，你可以直接让 AI 助手：

• "将这段中文生成音频文件"
• "用日语朗读下面这段文字，语速稍慢"
• "把长文拆分生成语音并合并为一个文件"

💻 开发

设置开发环境

git clone https://github.com/aardpro/mcp-melotts.git
cd mcp-melotts
pip install -e ".[dev]"

运行测试

pytest

构建包

build && upload

rm -rf dist && pip install build && python -m build && pip install twine && twine upload dist/*

pip install build
python -m build

发布到 PyPI

pip install twine
twine upload dist/*

修改后的发布步骤

当对项目进行修改后，按照以下步骤发布更新版本：

1. 在 pyproject.toml 中增加版本号
2. 安装构建依赖：

   pip install build twine
   

3. 构建包：

   python -m build
   

4. 本地测试构建的包（可选但推荐）：

   pip install dist/mcp_melotts-*.whl
   

5. 上传到 PyPI：

   twine upload dist/*
   

📂 项目结构

mcp-melotts/
├── src/
│   └── main/
│       ├── __init__.py
│       ├── __main__.py
│       └── server.py
├── pyproject.toml
├── README.md
└── LICENSE

❓ 常见问题

配置问题

请确保已安装 ffmpeg 与 MeloTTS，并能在 Python 中导入 melo.api。

音频生成失败

如果音频生成失败，请检查：

1. 是否已正确安装 MeloTTS（Python 包 melo）
2. 是否已正确设置语言与说话人标签
3. ffmpeg 是否在系统 PATH 中可用

📄 许可证

MIT License - 详见 LICENSE 文件。

🤝 贡献

欢迎提交 Pull Request 来改进这个项目！