Skip to main content
Glama

MiMo TTS MCP Server

通过 Model Context Protocol(MCP)调用小米 MiMo 语音合成模型,为 Claude Code、Codex、Cursor、Windsurf、VS Code 等 MCP 客户端提供语音合成能力。

覆盖 MiMo 三个 TTS 模型:预置音色、文本设计音色、音频样本复刻音色。

三个工具与三个模型的对应关系

工具

模型

音色来源

唱歌模式

text_to_speech

mimo-v2.5-tts

9 个内置音色

支持 (唱歌)

design_voice_to_speech

mimo-v2.5-tts-voicedesign

文本描述凭空生成

不支持

clone_voice_to_speech

mimo-v2.5-tts-voiceclone

本地 mp3/wav 样本

不支持

list_voices

—

返回音色/模型/配置目录,不需要 API Key

—

Related MCP server: MCP TTS Server

安装

npm install
npm run build

MCP 客户端配置(stdio):

{
  "mcpServers": {
    "mimo-tts": {
      "command": "node",
      "args": ["/absolute/path/to/mimo-tts-mcp/dist/bin/mimo-tts-mcp.js"],
      "env": {
        "MIMO_API_KEY": "your-mimo-api-key"
      }
    }
  }
}

Claude Code 一行添加:

claude mcp add mimo-tts -s user \
  -e MIMO_API_KEY=your-mimo-api-key \
  -- node /absolute/path/to/mimo-tts-mcp/dist/bin/mimo-tts-mcp.js

API Key 在 https://platform.xiaomimimo.com/console/api-keys 创建。TTS 系列目前限时免费。

环境变量

变量

必填

默认值

说明

MIMO_API_KEY

是(调用时)

—

MiMo API Key;也接受 XIAOMIMIMO_API_KEY

MIMO_BASE_URL

否

https://api.xiaomimimo.com/v1

改用 Token Plan 或自建网关时覆盖

MIMO_TTS_OUTPUT_DIR

否

~/mimo-tts

落盘目录,同时也是写入沙箱边界。支持 ~ 展开,相对路径按进程 cwd 解析后转成绝对路径

MIMO_TTS_TIMEOUT_MS

否

180000

单次请求超时

MIMO_TTS_ALLOW_ANY_PATH

否

未设置

设为 1 才允许写入 MIMO_TTS_OUTPUT_DIR 之外的任意路径

list_voices 不需要 Key,在 Key 缺失时仍可用于自检配置。

工具参数

text_to_speech

参数

必填

说明

text

是

要播报的文本。可在开头加风格标签 (怅然)、(东北话)、(唱歌),在句中插入 [轻笑]、[长叹一口气] 等音频标签

voice

否

内置音色 ID,默认 mimo_default

instructions

否

自然语言风格指令,走 user 消息,支持「角色/场景/指导」导演模式

format

否

wav(默认)或 mp3

output_path

否

输出文件路径,省略时写入 MIMO_TTS_OUTPUT_DIR;默认必须落在该目录内

file_name

否

省略 output_path 时使用的文件名主体

内置音色:mimo_default、冰糖、茉莉、苏打、白桦(中文);Mia、Chloe、Milo、Dean(英文)。

design_voice_to_speech

参数

必填

说明

voice_description

是

音色设计描述,1–4 句,覆盖性别年龄、音色质感、情绪语气、语速节奏,可选人设/场景/年代

text

条件

要播报的文本;当 optimize_text_preview 为 true 时可省略

optimize_text_preview

否

让模型润色文本,或在无文本时自动生成播报稿

format / output_path / file_name

否

同上

clone_voice_to_speech

参数

必填

说明

text

是

要播报的文本

sample_path

是

本地音色样本绝对路径,仅支持 .mp3 / .wav,建议 5–30 秒,Base64 后需小于 10 MB

instructions / format / output_path / file_name

否

同上

样本在每次调用时读取并转成 data:audio/...;base64,... 传给 API;文件只读不写。

安全模型

output_path 与 file_name 来自模型输出,因此按不可信输入处理:

  • 路径限制:默认只允许写入 MIMO_TTS_OUTPUT_DIR(默认 ~/mimo-tts)。该变量既决定默认落盘位置,也定义沙箱边界,因此建议按项目单独设置,例如 "MIMO_TTS_OUTPUT_DIR": "/path/to/project/audio"。越界路径、.. 穿越、以及指向目录外的符号链接子目录都会被拒绝。确实需要写任意位置时显式设置 MIMO_TTS_ALLOW_ANY_PATH=1。

  • 从不覆盖:目标已存在时不覆盖,自动改用 -2、-3 后缀,并用 wx 标志打开,因此也不会跟随已存在的符号链接写到别处。这样即使模型给出 ~/.bashrc 这类路径,也只会新建一个同名新文件,不会破坏原文件。

  • 文件名净化:file_name 中的路径分隔符会被清除,无法借它跳出目录。

  • 样本只读:sample_path 仅用于读取,从不写入。

  • 密钥只走环境变量:代码不读取配置文件、不写入磁盘、不打印日志;错误信息中不会回显 Key。

如果你的 MCP 客户端会执行模型生成的路径,建议保持默认(不放宽 MIMO_TTS_ALLOW_ANY_PATH)。

返回值

{
  "ok": true,
  "model": "mimo-v2.5-tts",
  "voice": "冰糖",
  "file": "/home/user/mimo-tts/20261020-110928-冰糖.wav",
  "format": "wav",
  "bytes": 148524,
  "duration_seconds": 1.55,
  "sample_rate": 24000,
  "streamed": true,
  "latency_ms": 1830
}

音频只写文件不内联 base64,避免把大 payload 灌进上下文。WAV 的 duration_seconds 由本地计算;mp3 需要逐帧解析才能精确,故不返回。若目标文件已存在,file 会带 -2 之类的后缀,这是正常行为而非错误。

实现要点

  • 端点:POST {baseUrl}/chat/completions,认证头 api-key,OpenAI Chat Completions 兼容。

  • 消息分工:assistant 存合成文本,user 存风格指令/音色描述。预置音色模型下 user 可省略;voicedesign 下 user 必填且不接受 audio.voice。

  • wav 走流式路径:MiMo 仅在 stream: true 时输出原始 pcm16,因此按 SSE 收集 choices[0].delta.audio.data、丢弃尾部不足一个采样的残字节,再本地封装 44 字节 WAV 头(24 kHz / 16-bit / 单声道)。

  • voicedesign 与 voiceclone 的流式接口目前降级为「推理完成后一次性返回」,流式拿不到音频时自动回退到非流式请求。

  • mp3 走非流式路径,直接取 choices[0].message.audio.data。

开发

npm run dev        # tsx 直接跑 stdio server
npm run typecheck
npm test           # vitest:请求体构造、SSE 拼帧、WAV 头、落盘路径与写入沙箱、MCP 工具契约
npm run build

参考

Available Tools

4 tools
clone_voice_to_speechMiMo TTS - cloned voiceA

Synthesize speech with Xiaomi MiMo mimo-v2.5-tts-voiceclone, replicating a voice from a local mp3/wav sample. The sample is Base64-encoded and sent on every call; MiMo requires it to stay under 10 MB. Writes the audio to a file and returns its path.

ParametersJSON Schema
NameRequiredDescriptionDefault
textYesText to speak. Audio tags such as (慵懒) or [叹气] are supported.
formatNoOutput container. wav is lossless and takes the low-latency streaming path; mp3 is smaller.wav
file_nameNoBase name used when output_path is omitted, e.g. "greeting".
output_pathNoWhere to write the audio file. Must stay inside MIMO_TTS_OUTPUT_DIR (~/mimo-tts) unless the server sets MIMO_TTS_ALLOW_ANY_PATH. A relative path resolves against the server process cwd. Existing files are never overwritten; a -2, -3 suffix is added instead.
sample_pathYesAbsolute path to the reference voice sample (.mp3 or .wav, ideally 5-30 seconds, under ~7.5 MB).
instructionsNoNatural-language style direction, sent as the user message. Describe emotion, pace, character, scene, or a director-style brief (角色/场景/指导). Audio tags such as (怅然) or [轻笑] belong in the spoken text instead.

TDQS

A3.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does well: it discloses that the sample is Base64-encoded and re-sent on every call, the ~10 MB payload ceiling, and that output is written to a file and returned as a path. It omits auth requirements, rate limits, and latency characteristics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences with no filler; the cloning purpose and model name lead, followed by the payload constraint and the output behavior. Every sentence contributes something an agent needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, yet the description still states that a file path is returned, and the payload/format constraints are covered between description and schema. Sufficient for correct invocation; only secondary operational details (permissions, quotas) are absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all six parameters in detail (format enum tradeoffs, output_path sandboxing and no-overwrite behavior, instructions usage). The description adds only the sample-size payload context, making 3 the appropriate baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (synthesize speech) plus the distinctive resource constraint: replicating a voice from a local mp3/wav sample via the named `mimo-v2.5-tts-voiceclone` model. An agent can infer this differs from `text_to_speech` (no sample) and `design_voice_to_speech`, but the description never names or contrasts those siblings explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied rather than stated: the requirement of a local reference sample tells the agent this is the path when a voice must be cloned. There is no explicit when-to-use/when-not, and no routing guidance toward `text_to_speech` for plain synthesis or `design_voice_to_speech` for novel voices.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

design_voice_to_speechMiMo TTS - designed voiceA

Synthesize speech with Xiaomi MiMo mimo-v2.5-tts-voicedesign, inventing a brand-new voice from a text description. No preset voice and no audio sample involved. Writes the audio to a file and returns its path.

ParametersJSON Schema
NameRequiredDescriptionDefault
textNoText to speak. Optional only when optimize_text_preview is true, in which case MiMo generates or polishes the script itself.
formatNoOutput container. wav is lossless and takes the low-latency streaming path; mp3 is smaller.wav
file_nameNoBase name used when output_path is omitted, e.g. "greeting".
output_pathNoWhere to write the audio file. Must stay inside MIMO_TTS_OUTPUT_DIR (~/mimo-tts) unless the server sets MIMO_TTS_ALLOW_ANY_PATH. A relative path resolves against the server process cwd. Existing files are never overwritten; a -2, -3 suffix is added instead.
voice_descriptionYesVoice design brief, 1-4 sentences. Cover dimensions such as gender and age, timbre, emotion, pace, plus optional persona/scene/era. Avoid post-processing terms (reverb, EQ) and contradictions.
optimize_text_previewNoLet MiMo polish the script (or invent one when text is omitted) before synthesis.

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden but only discloses the output contract: audio is written to a file and the path is returned. It says nothing about permissions, latency, cost, failure modes, or what the server does if synthesis fails, so it is a modest disclosure for an unannotated mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, zero filler: what the tool does, what it is not, and what it returns. The most important distinction is front-loaded before the output behavior.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 6-parameter tool with 100% schema coverage and no output schema, the description covers purpose, the model behind it, and the return shape (file path). It is essentially complete; only richer behavioral context (latency, auth, error handling) is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every parameter including voice_description, output_path restrictions and the text/optimize_text_preview interaction is already documented in the schema. The description adds no parameter-level semantics beyond what the schema supplies, which is the baseline 3 case.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Synthesize speech'), names the exact model ('mimo-v2.5-tts-voicedesign'), and pins the differentiator: a brand-new voice invented from a text description. The exclusions ('No preset voice and no audio sample') let an agent separate it from text_to_speech and clone_voice_to_speech without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The exclusions 'no preset voice and no audio sample involved' effectively define the selection condition against the two sibling TTS tools, and the phrase 'inventing a brand-new voice from a text description' signals the use case. It never names the alternatives explicitly, so it stops short of a full when/when-not routing statement.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_voicesMiMo TTS - catalogA

List the MiMo TTS models, their capabilities, built-in preset voices, and where files are written. Read-only; no API key needed.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the behavioral burden and usefully discloses that the operation is read-only and requires no API key. It also indirectly covers return content (models, capabilities, voices, file paths), though it omits error behavior or list stability details, which are minor for a zero-param catalog.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences, front-loaded with the core listing action, and the trailing safety note earns its place. Zero waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-param, no-output-schema catalog tool, the description covers what is listed and the key safety traits. A small gap remains in explicitly routing the agent from discovery to the sibling synthesis tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the baseline is 4. The description adds no parameter details and none are needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb 'List' and a detailed resource: MiMo TTS models, capabilities, preset voices, and file output locations. It is clearly a catalog tool distinct from the sibling synthesis/cloning tools, though it does not explicitly name them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Read-only; no API key needed' gives a calling hint, but there is no explicit when-to-use or when-not-to-use guidance relative to text_to_speech, design_voice_to_speech, or clone_voice_to_speech. The implied use is discovering voices before synthesis, but this is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

text_to_speechMiMo TTS - preset voiceA

Synthesize speech with Xiaomi MiMo mimo-v2.5-tts using one of the built-in voices. Supports singing via a leading (唱歌) tag, and fine-grained audio tags inside the text. Writes the audio to a file and returns its path, byte size, and duration.

ParametersJSON Schema
NameRequiredDescriptionDefault
textYesText to speak. Add a leading style tag such as (怅然) or (唱歌) and inline tags such as [轻笑] or [长叹一口气] to steer delivery. Keep it within a few thousand characters (8K token context).
voiceNoPreset voice id: mimo_default, 冰糖, 茉莉, 苏打, 白桦, Mia, Chloe, Milo, Dean. Chinese voices: mimo_default, 冰糖, 茉莉, 苏打, 白桦; English: Mia, Chloe, Milo, Dean.mimo_default
formatNoOutput container. wav is lossless and takes the low-latency streaming path; mp3 is smaller.wav
file_nameNoBase name used when output_path is omitted, e.g. "greeting".
output_pathNoWhere to write the audio file. Must stay inside MIMO_TTS_OUTPUT_DIR (~/mimo-tts) unless the server sets MIMO_TTS_ALLOW_ANY_PATH. A relative path resolves against the server process cwd. Existing files are never overwritten; a -2, -3 suffix is added instead.
instructionsNoNatural-language style direction, sent as the user message. Describe emotion, pace, character, scene, or a director-style brief (角色/场景/指导). Audio tags such as (怅然) or [轻笑] belong in the spoken text instead.

TDQS

A3.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description does the work: it discloses the side effect (writes an audio file), the return payload (path, byte size, duration), and the path constraints are further covered in the output_path schema. It omits auth/permission needs and rate limits, which is a modest gap for a mutation-with-artifact tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences with the core capability front-loaded and capabilities/return value following. No filler, though the singing and tag details could arguably merge into one clause.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 6-parameter tool with full schema coverage and no output schema, the description supplies the missing return-value summary (file path, size, duration) and the write side effect. Nothing critical is absent, though it says nothing about latency, cost, or error behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents voice, format, file_name, output_path and instructions thoroughly. The description's tag/singing note restates what text's schema description already says, so it adds little beyond the structured fields.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Synthesize speech with Xiaomi MiMo mimo-v2.5-tts") and narrows scope to "built-in voices", which implicitly separates it from design_voice_to_speech and clone_voice_to_speech. It stops short of naming those siblings outright, so the differentiation is inferable rather than explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The mention of "built-in voices" and the singing/tag capabilities implies when this tool is the right pick versus voice design or cloning, but no alternative is named and no exclusion is stated. Usage is inferable from context rather than spelled out.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv0.1.0
    • First observedclone_voice_to_speech
    • First observeddesign_voice_to_speech
    • First observedlist_voices
    • First observedtext_to_speech

TDQS

A4.1/5.0

Scored across 4 tools

Disambiguation5/5

The three synthesis tools are cleanly differentiated by voice source: preset built-in voice (text_to_speech), invented voice from a description (design_voice_to_speech), and replicated voice from an audio sample (clone_voice_to_speech). list_voices is clearly read-only and metadata-focused, so there is no realistic misselection.

Naming Consistency5/5

All three synthesis tools follow a predictable '<source>_to_speech' pattern, and the read-only tool uses the conventional 'list_<noun>' form. The convention is consistent and self-explanatory across the whole set.

Tool Count5/5

Four tools is well-scoped for a TTS server: three synthesis modes plus one discovery/introspection tool. Each tool earns its place with no filler or redundancy.

Completeness4/5

The surface covers the key TTS lifecycle modes (preset, design, clone) plus model/voice discovery, which is strong for the domain. Minor gaps exist around managing generated output (e.g. listing or deleting written files), but agents can work around this via the returned file paths.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    F
    maintenance
    MCP server for the Supertone TTS API. Generate natural speech, browse and preview the voice catalog, predict synthesis cost, and create cloned voices — directly from Claude Desktop, Cursor, or any MCP-compatible client. Supports Korean, English, Japanese, and 20+ other languages, with speed, pitch, and emotion-style control.
    14
    4
    MIT
  • F
    license
    Not graded
    quality
    D
    maintenance
    Provides text-to-speech conversion through a unified MCP interface, supporting both local Kokoro and cloud OpenAI TTS engines with streaming audio, voice selection, and customization via natural language instructions.
    7
    -
  • A
    license
    Not graded
    quality
    D
    maintenance
    Multi-engine text-to-speech for AI coding assistants. Speaks responses aloud from Claude Code, Cursor, or VS Code via a Claude Code plugin, MCP server, or CLI pipe.
    68 PyPI
    MIT