Skip to main content
Glama
Komorebi-yaodong

oai-tts

by Komorebi-yaodong
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
TypeScript
Remote

oai-tts-mcp

一个 OpenAI 兼容 TTS MCP 服务。AI 可调用它来：

  1. 查询当前模型的可用音色；

  2. 将文本按指定音色和语气转换为音频。

功能

  • list_voices

    • 默认请求 GET /v1/tts/voices?model={OAI_TTS_MODEL}。

    • 对 Base URL 自动规整：https://host 与 https://host/v1 均可，绝不会产生 /v1/v1。

    • 上游请求失败、超时或响应不包含有效 voices[] 时，返回内置回退音色，并标记 source: "fallback" 和原因。

  • text_to_speech

    • 请求 POST /v1/audio/speech。

    • 传入 instructions 即可要求语气/表达，例如“平静、温暖、适合睡前故事，语速自然，句末轻柔收束”。

    • 默认 speed 是 1.25；可选范围 0.25 到 4。

    • 将音频上传至 Urusai 文件托管并返回公开 HTTPS URL；不返回 Base64 音频，减少上下文和客户端兼容性问题。

要求

  • Node.js >= 20

  • pnpm

  • 有效的 OpenAI 或 OpenAI 兼容 TTS 服务地址与 API Key

通过 npx 使用

发布到 npm 后，无需全局安装。MCP 客户端可直接调用：

{
  "mcpServers": {
    "oai-tts": {
      "command": "npx",
      "args": ["-y", "oai-tts-mcp"],
      "env": {
        "OAI_TTS_BASE_URL": "https://api.openai.com/v1",
        "OAI_TTS_API_KEY": "your_api_key_here",
        "OAI_TTS_MODEL": "gpt-4o-mini-tts",
        "OAI_TTS_VOICE": "marin",
        "URUSAI_API_TOKEN": "your_optional_urusai_token"
      }
    }
  }
}

npx -y 会下载并启动 npm 上的最新版本。请始终通过客户端的受保护环境变量注入 Key/Token，勿将真实凭据写入配置仓库。

安装

Set-Location "E:\Programming\oai-tts-mcp"
pnpm install

参照仓库内的 env.example，将以下变量填入 MCP 客户端的 env 配置或受保护的系统环境变量：

OAI_TTS_BASE_URL=https://api.openai.com/v1
OAI_TTS_API_KEY=your_api_key_here
OAI_TTS_MODEL=gpt-4o-mini-tts
OAI_TTS_VOICE=marin

# 可选：Urusai 图床访问令牌。音频将上传至第三方并返回公开 URL；请勿上传敏感内容。
URUSAI_API_TOKEN=your_optional_urusai_token

# 可选：默认 https://api.urusai.cc/v1/upload；仅用于自建兼容上传服务或本机测试。
URUSAI_UPLOAD_URL=https://api.urusai.cc/v1/upload

推荐模型为 gpt-4o-mini-tts，它支持使用 instructions 细调表达。兼容服务是否支持该字段及具体音色，以该服务的实现为准。

构建与启动

pnpm build
pnpm start

开发时：

pnpm dev

MCP 使用 stdio 通信；不要把服务日志写入 stdout。运行日志仅输出至 stderr。

MCP 客户端配置示例

以支持 stdio MCP 的客户端为例，配置命令为：

{
  "mcpServers": {
    "oai-tts": {
      "command": "node",
      "args": ["E:\\Programming\\oai-tts-mcp\\dist\\index.js"],
      "env": {
        "OAI_TTS_BASE_URL": "https://api.openai.com/v1",
        "OAI_TTS_API_KEY": "your_api_key_here",
        "OAI_TTS_MODEL": "gpt-4o-mini-tts",
        "OAI_TTS_VOICE": "marin",
        "URUSAI_API_TOKEN": "your_optional_urusai_token",
        "URUSAI_UPLOAD_URL": "https://api.urusai.cc/v1/upload"
      }
    }
  }
}

服务仅从进程环境变量读取配置；由 MCP 客户端 env 注入是推荐且安全的方式。

工具说明

list_voices

无参数。返回文本摘要和结构化结果：

{
  "voices": [
    { "voice_id": "eve", "name": "Eve", "language": "en" }
  ],
  "source": "remote"
}

若远程音色接口不可用，则返回 source: "fallback"。内置回退集为：

alloy、ash、ballad、coral、echo、fable、nova、onyx、sage、shimmer、verse、marin、cedar。

tts-1 与 tts-1-hd 的可用音色较少；请优先调用 list_voices，并以远程结果为准。

text_to_speech

参数：

参数

必填

说明

input

是

要朗读的文本，最多 4096 个字符。

voice

否

音色 ID；缺省时使用OAI_TTS_VOICE。

instructions

否

语气、情绪、节奏、口音或表达方式；gpt-4o-mini-tts 支持效果最佳。

speed

否

语速倍率，默认1.25，范围 0.25–4。

response_format

否

mp3（默认）、opus、aac、flac、wav 或 pcm。

成功时工具仅返回文本 JSON 和结构化结果，其中 url 是图床返回的公开直链：

{
  "status": "success",
  "url": "https://example.com/oai-tts-...-Eve.mp3",
  "model": "grok-voice-think-fast-2.0",
  "voice": "Eve",
  "speed": 1.25,
  "format": "mp3",
  "mime_type": "audio/mpeg"
}

图床上传失败时，本次调用会返回错误，不会返回 Base64 音频或本地临时路径。

调用意图示例：

使用 text_to_speech，以 marin 音色、温暖平静的睡前故事语气朗读这段文本。

图床上传与安全说明

  • text_to_speech 将音频二进制上传到 Urusai 默认端点 https://api.urusai.cc/v1/upload，成功后使用响应内的 data.url_direct 作为公开直链。

  • 生成的音频会离开本机并可能被持有 URL 的人访问；不要对机密、隐私、个人信息或未获授权的内容使用此工具。

  • URUSAI_API_TOKEN 是可选的上传服务令牌；URUSAI_UPLOAD_URL 仅用于覆盖默认端点（例如自建兼容服务）。不要把任一令牌提交到 Git。

  • TTS API Key 和上传 Token 均不会被写入日志、构建产物或仓库；请仅通过 MCP 客户端 env 或受保护的系统环境变量提供。

  • list_voices 上游请求失败会静默降级为公开内置列表；TTS 或上传失败会返回安全的错误摘要，不回显认证信息。

参考