Cantonese.ai MCP Server

Cantonese.ai MCP 服务

一个 MCP（Model Context Protocol）服务，使用 cantonese.ai API 提供文本转语音和语音转文本转换工具。此服务旨在通过 mcp dev 运行。

---

✨ 功能

• 文本转语音工具：将粤语或英语文本转换为高质量音频。
• 语音转文本工具：将音频文件转录为文本。
• 现代化工具：使用 uv 设置，实现快速的包管理。
• 轻松集成：可连接任何兼容 MCP 的客户端（例如，大模型 Agent）。
• 安全：你的 cantonese.ai API 密钥将作为环境变量安全处理。

---

🚀 开始使用

前提条件

• Python 3.8+
• uv：我们建议使用 uv 管理 Python 包。

安装

1. 克隆仓库：

   git clone 
   cd cantonese-ai-mcp-server
   

2. 创建并激活虚拟环境：

   uv venv
   source .venv/bin/activate
   

3. 安装依赖项： 此项目使用 uv 从 pyproject.toml 同步依赖项。

   uv sync
   

4. 设置 API 密钥： 你需要一个来自 cantonese.ai 的 API 密钥。将 API 密钥导出为环境变量。你可以将其添加到 .bashrc 或 .zshrc 文件中，以便持久保存。

   export CANTONESE_AI_API_KEY="your-api-key-here"
   

运行服务

使用以下命令启动 MCP 开发服务。它会监视 server.py 中的更改并自动重新加载。

uv run mcp dev server.py

你应该会看到服务已启动并可用的提示，通常地址为 http://127.0.0.1:6274。

或者

运行服务并在 Claude Desktop 中使用

uv run server.py

请参阅服务器开发者指南，了解如何设置与 Cladue Desktop 的连接。

🛠️ 使用工具

服务运行后，将提供两个工具。

工具：text_to_speech

将文本字符串转换为音频文件。

参数：

-text（字符串，必填）：要转换为语音的文本。 -voice（字符串，可选，默认值："default"）：用于语音合成的声音。 -language（字符串，可选，默认值："cantonese"）：文本的语言。可以是 "cantonese" 或 "english"。 -output_filename（字符串，必填）：用于保存音频的文件名（例如，output.mp3）。

调用示例：

{
  "tool": "text_to_speech",
  "arguments": {
    "text": "你好世界",
    "output_filename": "hello_world.mp3"
  }
}

成功响应：

{
  "success": true,
  "message": "Audio file saved as hello_world.mp3"
}

工具：speech_to_text

将音频文件转录为文本。

参数：

input_filename（字符串，必填）：要转录的本地音频文件路径（例如，audio.wav）。

调用示例：

{
  "tool": "speech_to_text",
  "arguments": {
    "input_filename": "audio.wav"
  }
}

成功响应：

该工具将返回一个 JSON 对象，其中包含 API 返回的转录详情。

{
  "success": true,
  "result": {
    "text": "你好世界",
    "confidence": 0.95,
    "language": "cantonese",
    "duration": 2.3,
    "timestamp": "2025-06-02T11:22:00Z"
  }
}

📜 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。