edge-tts-mcp

Overview Schema Source Related Servers Discussions Admin

tts

Generate MP3 or OGG/Opus audio from text via Edge speech synthesis, with optional SRT/VTT subtitles, word timings, and local output paths for captioned or timed audio workflows.

Instructions

Generate MP3 or OGG/Opus (requires FFmpeg) and return a local file path.

Rate/volume: signed percentage, e.g. +10%. Pitch: signed Hz, e.g. -5Hz. Ordinary speech/Telegram: leave subtitles=none and word_timings=false. Request srt/vtt only for captions; request word_timings only for per-word highlighting/editing. Missing boundary events return audio with warnings, never estimated timings. Explicit voice/rate/volume/pitch override server defaults. Choose rate directly for the task, e.g. +15% or -10%. Optional target_duration_seconds fits audio duration with FFmpeg, verified by FFprobe. Omitted parameters inherit config.py ENV defaults (built-in tempo 0.5–2.0). Set tempo_min/tempo_max for the task (immutable technical limits 0.5–2.0). Bounds are never widened automatically; retry explicitly to change them. Unreachable targets return target_duration_unreachable with required tempo and bounds, not original audio. Without a target, tempo bounds do not change audio. Check duration_fitting.target_met and warnings; precise sync/natural speech are not guaranteed. Timings are rescaled using the applied tempo. Successful requests create audio; subtitles and word timings are optional sidecar files. Timeout includes queue wait, retries, synthesis, conversion and sidecars. Up to 100000 characters; max_audio_duration_seconds limits audio duration independently of the operation timeout. Targets must not exceed that duration limit; oversized output is not trimmed or published. for long jobs increase timeout and client's deadline or shorten text. Check success/warnings before using audio_path, subtitle_path or word_timings_path. Paths are local to the MCP host, not uploaded.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "text": "<text>"
    },
    "name": "tts"
  }
}

Input Schema

Name	Required	Default
`rate`	No
`text`	Yes
`pitch`	No
`voice`	No
`volume`	No
`timeout`	No
`subtitles`	No	none
`tempo_max`	No
`tempo_min`	No
`audio_format`	No	mp3
`word_timings`	No
`target_duration_seconds`	No
`max_audio_duration_seconds`	No

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.3.2Nov 6, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Annotations already declare non-read-only, non-idempotent, open-world behavior; the description adds substantially more: missing boundary events return audio with warnings rather than estimated timings, unreachable targets return target_duration_unreachable with required tempo/bounds instead of original audio, tempo bounds are never auto-widened, oversized output is not trimmed or published, and timeout includes queue wait, retries, synthesis and sidecars. Paths being local to the MCP host (not uploaded) is exactly the kind of context annotations can't carry.

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

Conciseness3/5

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

Purpose is front-loaded, but the body is a wall of short wrapped lines with repetition ('Choose rate directly for the task, e.g. +15% or -10%' restates the earlier rate line) and two separate warning-check instructions. The information is valuable but not grouped or prioritized, making it harder to scan than it needs to be.

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 13-parameter tool it covers limits (100000 characters), timeout semantics, target feasibility failure modes, sidecar files, and how to check success before consuming output paths; with an output schema present it correctly avoids explaining return structure in depth. The main omission is failing to point at list_voice for valid voice values, which leaves one required decision path unaddressed.

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?

Schema description coverage is 0%, so the description carries the full burden, and it delivers for most params: signed percentage for rate/volume with examples, signed Hz for pitch, subtitles enum usage, word_timings purpose, target_duration_seconds fitting verified by FFprobe, tempo_min/tempo_max limits, and max_audio_duration_seconds acting independently of timeout. The voice parameter is only described as overriding server defaults, with no hint about accepted values or where to discover them.

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?

Opens with a specific verb and resource ('Generate MP3 or OGG/Opus ... return a local file path') and notes the FFmpeg dependency for OGG. The sibling tools (get_capabilities, list_voice) are clearly metadata/discovery tools, so the synthesis-focused purpose is unmistakable.

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?

Gives concrete conditional guidance: leave subtitles=none and word_timings=false for ordinary speech/Telegram, request srt/vtt only for captions, request word_timings only for per-word highlighting, and increase timeout or shorten text for long jobs. It never names list_voice or get_capabilities as alternatives for choosing a voice or checking capabilities, which is the one missing routing hint.

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

Deploy Server

tts