edge-tts-mcp

Асинхронный MCP-сервер синтеза речи Microsoft Edge с транспортом stdio. Создаёт MP3, OGG/Opus, субтитры SRT/WebVTT и JSON с таймингами слов. Аудиофайл создаётся всегда; субтитры и тайминги добавляются по запросу.

Требуется Python 3.12+. Для MP3 и субтитров FFmpeg не нужен. Для OGG/Opus нужен FFmpeg с поддержкой libopus. Текст отправляется в онлайн-сервис Microsoft; офлайн-режима нет.

Структура

main.py                 # запуск из корня проекта
edge_tts_mcp/
    __main__.py         # запуск через python -m edge_tts_mcp
    cli.py              # аргументы CLI и запуск сервера
    server.py           # MCP-инструменты и настройки окружения
    service.py          # синтез и публикация файлов
    audio.py            # проверка аудио и конвертация FFmpeg
    timings.py          # тайминги слов и формирование субтитров
Dockerfile
compose.yaml
tests/
pyproject.toml          # метаданные пакета и настройки разработки
requirements.txt        # прямые зависимости с фиксированными версиями

Все способы запуска используют одну функцию edge_tts_mcp.cli:main: python main.py, python -m edge_tts_mcp и установленная команда edge-tts-mcp.

Related MCP server: Edge-TTS MCP Server

Установка и запуск

Из корня проекта, Windows / PowerShell:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe main.py --help
.\.venv\Scripts\python.exe main.py

Linux / macOS:

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python main.py --help
.venv/bin/python main.py

Сервер ожидает сообщения MCP в stdin. Это не интерактивная TTS-консоль. Для установки как пакета выполните python -m pip install . в выбранном окружении. После этого команда edge-tts-mcp доступна и вне каталога проекта.

requirements.txt и метаданные пакета содержат одинаковые прямые зависимости в формате библиотека==версия; их соответствие проверяется тестом. Транзитивные зависимости разрешает установщик. Lock-файл для установки не требуется.

Подключение MCP

Укажите абсолютный путь к Python из окружения и к main.py:

{
  "mcpServers": {
    "edge-tts-mcp": {
      "command": "/absolute/path/to/project/.venv/bin/python",
      "args": ["/absolute/path/to/project/main.py"],
      "env": {"EDGE_TTS_OUTPUT_DIR": "/absolute/path/to/output"}
    }
  }
}

На Windows используйте путь вида F:/Projects/edge-tts-mcp/.venv/Scripts/python.exe. Если пакет установлен, вместо пути к main.py можно передать ["-m", "edge_tts_mcp"]. Таймаут MCP-клиента должен быть больше таймаута инструмента, например 60 секунд при стандартном лимите синтеза 45 секунд.

Инструменты

get_capabilities()

Возвращает форматы, наличие исполняемого FFmpeg, ограничения, настройки голоса, профили и доступность субтитров и таймингов. Сетевых запросов не делает. Наличие FFmpeg не гарантирует поддержку libopus.

list_voice(locale="", gender="", query="", offset=0, limit=null)

Без аргументов возвращает все голоса. locale фильтрует по префиксу без учёта регистра (ru, ru-RU, en), gender принимает Female, Male или пустую строку. query ищет по метаданным, offset и limit задают страницу результатов. Поле ShortName из ответа передаётся в tts.voice. Сетевой запрос ограничен 30 секундами; ошибка не маскируется пустым списком.

tts

Обычное аудио:

{"text": "Привет! Проверка синтеза речи."}

Аудио OGG/Opus и субтитры:

{"text": "Привет, мир!", "audio_format": "ogg", "subtitles": "vtt"}

Аудио и тайминги слов:

{"text": "Привет, мир!", "word_timings": true}

Тайминги соответствуют созданной озвучке с выбранным голосом и скоростью. Это не распознавание существующей записи и не выравнивание по стороннему аудио или видео.

Успешный ответ содержит success: true и path к основному файлу:

• Всегда: audio_path, size, duration_seconds, format, mime_type — данные аудиофайла.

• С субтитрами: subtitle_path, subtitle_format.

• С таймингами: word_timings_path, word_count. JSON содержит объекты {"word": "Привет", "start_ms": 100, "end_ms": 500}.

По умолчанию создаётся только аудио. Субтитры и тайминги появляются по запросу. Если события слов отсутствуют или некорректны, запрос возвращает аудио и предупреждение timing_metadata_unavailable. Пустые субтитры и выдуманные тайминги не публикуются. Слова группируются в короткие фразы; пунктуация и написание могут быть нормализованы сервисом. Субтитры не встраиваются в видео.

Профиль default использует настройки сервера. narration задаёт скорость -10%, notification — +15%, slow — -25%, с нейтральной громкостью и высотой. Явные параметры вызова перекрывают профиль. Профили не меняют голос и не задают эмоции.

Таймаут включает очередь, синтез, конвертацию и запись результатов. Длинный текст разбивается библиотекой с сохранением сквозных смещений. Для него увеличьте таймаут инструмента и клиента; лимит 100000 символов не гарантирует завершения за 300 секунд.

Ошибки возвращают success: false, error_code и error. Коды: invalid_input, timeout, no_audio, audio_error, io_error, service_error, feature_disabled. Нарушение MCP-схемы аргументов возвращается как ошибка инструмента.

Настройки

CLI имеет приоритет над окружением. Файлы .env автоматически не загружаются. Булевы настройки принимают 1/0, true/false, yes/no, on/off. Неверные настройки останавливают запуск с понятной ошибкой.

Пути в ответе относятся к машине MCP-сервера. Сервер создаёт файлы локально, не воспроизводит их и никуда не загружает. Готовые файлы остаются до удаления пользователем. Временные файлы удаляются при обычных ошибках и отмене запроса. Каждый файл публикуется атомарно; набор файлов не является транзакцией при аварийном завершении процесса. Новые каталоги на POSIX создаются с правами 0700, готовые файлы — 0600; на Windows действуют наследуемые ACL.

Docker

Сборка из корня проекта:

docker build -t edge-tts-mcp:local .
docker run --rm edge-tts-mcp:local --version
docker run --rm --init -i -v speech-output:/data/output edge-tts-mcp:local

Или через Compose:

docker compose build
docker compose run --rm -T edge-tts-mcp

Контейнер содержит FFmpeg и работает от непривилегированного пользователя. Для stdio используйте -i без -t; сетевых портов нет. Результаты в примере сохраняются в именованном томе. Для доступа с хоста используйте bind mount и учитывайте отображение путей: возвращаемый /data/output/... — путь внутри контейнера. При необходимости задайте APP_UID и APP_GID при сборке под владельца каталога хоста.

Разработка

В виртуальном окружении установите проект и инструменты разработки:

python -m pip install -e . --group dev
python -m pytest -q
python -m ruff check .
python -m ruff format --check .
python -m mypy
python -m bandit -q -r edge_tts_mcp
python -m pytest -q --cov=edge_tts_mcp
python -m pip wheel --no-deps --wheel-dir dist .

Опция --group требует pip 25.1+. Вместо pip можно использовать uv pip install -e . --group dev с выбранным виртуальным окружением. FFmpeg для офлайн-тестов поставляется отдельной тестовой зависимостью. Обычный запуск тестов не обращается к Microsoft и не требует Docker.

Проверки настоящего сервиса включаются явно, например в PowerShell:

$env:EDGE_TTS_LIVE_TESTS = "1"
python -m pytest -q -m live -k "not long_text and not container"
Remove-Item Env:EDGE_TTS_LIVE_TESTS

Тесты контейнера требуют собранного образа и запущенного Docker:

$env:EDGE_TTS_DOCKER_TESTS = "1"
python -m pytest -q -m "docker and not live"
Remove-Item Env:EDGE_TTS_DOCKER_TESTS

Лицензия кода проекта: MIT, см. LICENSE. Зависимости распространяются по собственным лицензиям. Проект не является официальным продуктом Microsoft.