typecast-api-mcp-server-sample

typecast-api-mcp-server

面向 typecast-api 的 MCP 服务，可与 MCP 客户端无缝集成。本项目通过模型上下文协议，提供与 Typecast API 交互的标准化方式。

关于

本项目为 Typecast API 实现了模型上下文协议服务端，让 MCP 客户端能够以标准化方式与 Typecast API 交互。

支持的模型

模型	说明	情绪控制
ssfm-v30	最新模型（推荐）	预设 + 智能模式
ssfm-v21	稳定的生产模型	仅预设

ssfm-v30 功能

• 7 种情绪预设：normal、happy、sad、angry、whisper、toneup、tonedown
• 智能模式：AI 使用 previous_text 和 next_text 根据上下文自动推断情绪
• 37 种语言：扩展语言支持

功能实现状态

功能	状态
语音管理
搜索文档	✅
获取语音（V3 API）	✅
获取语音 use_cases 筛选条件	✅
获取语音（V3 API）	✅
推荐语音	✅
文本转语音	✅
文本转语音（流式）	✅
文本转语音（带时间戳）	✅
获取我的订阅	✅
播放音频	✅
输出控制
target_lufs 响度标准化	✅
ssfm-v30 支持
预设模式	✅
智能模式	✅
自定义语音
即时 / 专业克隆	✅
列出 / 获取 / 删除自定义语音	✅

快速语音克隆

MCP 服务提供当前自定义语音 API 的工具：

• clone_voice：从本地 WAV 或 MP3 文件快速克隆自定义语音。
• create_professional_voice：启动专业克隆；使用前请轮询其状态。
• get_custom_voices 和 get_custom_voice：列出语音或查看克隆状态。
• delete_cloned_voice：删除以 uc_ 开头的克隆语音 ID。

即时克隆限制：

• 语音名称必须为 1–30 个字符。
• 音频样本必须为 WAV 或 MP3 格式。
• 音频样本不得超过 25 MB。
• 除非有特定的兼容性原因，否则请使用 ssfm-v30。

典型流程：

1. 使用 name、audio_file_path 和可选的 model 运行 clone_voice。
2. 在 text_to_speech、text_to_speech_stream 或 text_to_speech_with_timestamps 中使用返回的 next_step_voice_id 和 next_step_model。
3. 临时克隆语音不再需要时，运行 delete_cloned_voice。

专业克隆会返回 202 Accepted。轮询 get_custom_voice，直到其 状态变为 completed 或 failed；完成过程最长可能需要两小时。

语音推荐

如果你知道所需的风格、情绪、语言或使用场景，但尚不知道确切的语音 ID，请使用 recommend_voices。它会调用 GET /v1/voices/recommendations，并按得分排序返回候选项。

推荐响应有意仅包含 voice_id、 voice_name 和 score。如果 Agent 需要了解推荐语音的详细信息， 请对每个返回的 ID 调用 get_voice，或使用 get_voices 获取范围更广的筛选列表， 然后再在 TTS 中使用该 ID。

设置

托管服务

托管的 Streamable HTTP 端点为：

https://typecast-api-docs-web-production.up.railway.app/mcp

未进行身份验证时，服务仅提供 search_documentation。每次 MCP 请求都需发送 Typecast API 密钥，才能使用 Typecast API 工具：

X-API-KEY: YOUR_TYPECAST_API_KEY

也支持 Authorization: Bearer YOUR_TYPECAST_API_KEY。托管服务不会存储密钥。生成的音频会通过私有且不可猜测的下载 URL 返回，并在一小时后过期。play_audio 仍是仅限本地使用的工具，因为托管服务无法在 MCP 客户端的设备上播放声音。

为了保留 Typecast 集成代码的创建来源，托管客户端可以同时发送以下两个归属标头：

X-Typecast-Integration-Source: api-docs
X-Typecast-Generated-By: codex

API 页面引导使用 api-page，API 文档引导使用 api-docs。旧版 llms 和 skill 值仍受支持。X-Typecast-Generated-By 接受最长 32 个字符的小写 ASCII 令牌。服务会保留自己的 typecast-mcp/<version> User-Agent，并附加此归属信息，而不是将其替换。

在托管服务上，clone_voice 仅接受 audio_base64，并要求同时提供以 .wav 或 .mp3 结尾的 audio_filename。audio_file_path 仅在此 MCP 服务于本地运行时可用。

环境变量

设置以下环境变量：

TYPECAST_API_KEY=<your-api-key>
TYPECAST_OUTPUT_DIR=<your-output-directory> # default: ~/Downloads/typecast_output
TYPECAST_INTEGRATION_SOURCE=<llms|skill|api-page|api-docs> # optional; set both attribution variables
TYPECAST_GENERATED_BY=<coding-agent-id>                     # optional; e.g. codex or claude-code

在 Claude Desktop / Cursor 中使用

你可以将以下内容添加到 claude_desktop_config.json 或 Cursor MCP 设置中：

推荐：使用 uvx（无需安装）

{
  "mcpServers": {
    "typecast-api-mcp-server": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/neosapience/typecast-api-mcp-server.git",
        "typecast-api-mcp-server"
      ],
      "env": {
        "TYPECAST_API_KEY": "YOUR_API_KEY",
        "TYPECAST_OUTPUT_DIR": "PATH/TO/YOUR/OUTPUT/DIR"
      }
    }
  }
}

此方法会自动从 GitHub 获取并运行服务，无需手动克隆。

Linux 用户须知：如果你在 Linux 上运行，需要在 env 部分添加 XDG_RUNTIME_DIR 环境变量：

"env": {
  "TYPECAST_API_KEY": "YOUR_API_KEY",
  "TYPECAST_OUTPUT_DIR": "PATH/TO/YOUR/OUTPUT/DIR",
  "XDG_RUNTIME_DIR": "/run/user/1000"
}

替代方案：本地安装

如果你希望克隆并在本地运行：

Git 克隆

git clone https://github.com/neosapience/typecast-api-mcp-server.git
cd typecast-api-mcp-server

依赖项

此项目需要 Python 3.10 或更高版本，并使用 uv 进行包管理。

# Create virtual environment and install packages
uv venv
uv pip install -e .

本地配置

{
  "mcpServers": {
    "typecast-api-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/PATH/TO/YOUR/PROJECT",
        "run",
        "typecast-api-mcp-server"
      ],
      "env": {
        "TYPECAST_API_KEY": "YOUR_API_KEY",
        "TYPECAST_OUTPUT_DIR": "PATH/TO/YOUR/OUTPUT/DIR"
      }
    }
  }
}

将 /PATH/TO/YOUR/PROJECT 替换为项目所在的实际路径。

手动执行

你也可以手动运行服务：

uv run python app/main.py

参与贡献

欢迎随时贡献！欢迎提交 Pull Request。

许可证

MIT 许可证