tts-mcp-server 0.1.1__tar.gz

tts_mcp_server-0.1.1/.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.coverage
+.env
+*.mp3
+*.wav
+*.srt
+*.vtt
+# real example outputs are committed on purpose
+!examples/**/*.mp3
+!examples/**/*.wav
+!examples/**/*.srt
+!examples/**/*.vtt

tts_mcp_server-0.1.1/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.1] - 2026-11-08
+
+### Changed
+- Published on PyPI and Docker Hub as **`tts-mcp-server`** (`uvx tts-mcp-server`, `docker run -i --rm -e MIRAGEA_API_KEY miragea/tts-mcp-server`). The `miragea-voice-mcp` command stays installed as an alias, so existing configs keep working.
+- Client snippets now use the server key `tts` and the PyPI package instead of a git URL.
+- MCP Registry name is `io.github.RTY2345RR/tts-mcp-server` (PyPI + OCI packages).
+
+### Fixed
+- Subtitles: words that speech recognition cut across two cues ("an" | "d bruised") are re-joined at word boundaries, and stray punctuation-only cues are merged. SRT, VTT and JSON are now always rendered from the cleaned segments.
+
+### Added
+- `examples/` with real outputs: YouTube voiceover with SRT, two-voice dialogue, and transcription to captions.
+
+## [0.1.0] - 2026-11-08
+
+### Added
+- stdio MCP server `miragea-voice-mcp`, runnable with `uvx --from git+https://github.com/RTY2345RR/miragea-voice-mcp miragea-voice-mcp` (PyPI release `uvx miragea-voice-mcp` coming soon).
+- Tools: `miragea_get_capabilities`, `miragea_list_voices`, `miragea_text_to_speech`,
+  `miragea_transcribe`, `miragea_script_to_voiceover`, `miragea_get_task`, `miragea_list_tasks`.
+- One-shot script → voiceover + SRT/VTT captions, with script-accurate caption wording and
+  short-form cue splitting (`max_caption_chars`).
+- Local WebVTT rendering from Miragea's timed segments.
+- No duplicate jobs on retry: idempotency keys on every job, automatic retries reuse the same key,
+  timeouts return a resumable `task_id`, pre-flight validation against live capabilities.
+- `--check` (read-only key/API check) and `--print-config` for Claude Desktop, Claude Code, Cursor,
+  Codex, VS Code and Windsurf.
+- Compatible with MCP Python SDK 1.x (`FastMCP`) and 2.x (`MCPServer`).
+- Companion Agent Skill `skills/miragea-voiceover`.
+- Registry metadata: `server.json`, `smithery.yaml`, `glama.json`, `llms.txt`.
+
+[Unreleased]: https://github.com/RTY2345RR/miragea-voice-mcp/compare/v0.1.1...HEAD
+[0.1.1]: https://github.com/RTY2345RR/miragea-voice-mcp/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/RTY2345RR/miragea-voice-mcp/releases/tag/v0.1.0

tts_mcp_server-0.1.1/Dockerfile

@@ -0,0 +1,10 @@
+# Minimal image for registries that build MCP servers in containers (Glama, Smithery).
+FROM python:3.12-slim
+ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 MIRAGEA_OUTPUT_DIR=/data
+WORKDIR /app
+COPY pyproject.toml README.md LICENSE ./
+COPY src ./src
+RUN pip install --no-cache-dir . && mkdir -p /data
+VOLUME ["/data"]
+LABEL io.modelcontextprotocol.server.name="io.github.RTY2345RR/tts-mcp-server"
+ENTRYPOINT ["tts-mcp-server"]

tts_mcp_server-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Miragea
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tts_mcp_server-0.1.1/PKG-INFO

@@ -0,0 +1,361 @@
+Metadata-Version: 2.5
+Name: tts-mcp-server
+Version: 0.1.1
+Summary: TTS MCP server: text-to-speech, AI voiceover, voice cloning and SRT/VTT subtitles for Claude, Cursor, Codex and other AI agents.
+Project-URL: Homepage, https://github.com/RTY2345RR/miragea-voice-mcp
+Project-URL: Demo, https://huggingface.co/spaces/miragea/miragea-voice-mcp
+Project-URL: Voice engine, https://miragea.ai
+Project-URL: PyPI, https://pypi.org/project/tts-mcp-server/
+Project-URL: Docker, https://hub.docker.com/r/miragea/tts-mcp-server
+Project-URL: Repository, https://github.com/RTY2345RR/miragea-voice-mcp
+Project-URL: Documentation, https://github.com/RTY2345RR/miragea-voice-mcp#readme
+Project-URL: Issues, https://github.com/RTY2345RR/miragea-voice-mcp/issues
+Project-URL: Changelog, https://github.com/RTY2345RR/miragea-voice-mcp/blob/main/CHANGELOG.md
+Project-URL: API keys, https://miragea.ai/workspace/api
+Author: Miragea
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-voice,ai-voiceover,captions,claude,codex,cursor,elevenlabs-alternative,mcp,mcp-server,miragea,model-context-protocol,speech-to-text,srt,subtitles,text-to-speech,text-to-speech-mcp,transcription,tts,tts-mcp,tts-mcp-server,video-creator,voice-cloning,voiceover,vtt,youtube-shorts
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio :: Conversion
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<3,>=1.9
+Provides-Extra: dev
+Requires-Dist: anyio>=4; extra == 'dev'
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# TTS MCP Server — text-to-speech, AI voiceover, voice cloning and SRT/VTT subtitles for Claude, Cursor and Codex
+
+[![CI](https://github.com/RTY2345RR/miragea-voice-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/RTY2345RR/miragea-voice-mcp/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/v/release/RTY2345RR/miragea-voice-mcp)](https://github.com/RTY2345RR/miragea-voice-mcp/releases)
+[![PyPI](https://img.shields.io/pypi/v/tts-mcp-server.svg)](https://pypi.org/project/tts-mcp-server/)
+[![Docker](https://img.shields.io/badge/docker-miragea%2Ftts--mcp--server-2496ED.svg)](https://hub.docker.com/r/miragea/tts-mcp-server)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)
+[![Hugging Face Space](https://img.shields.io/badge/%F0%9F%A4%97%20Demo-Hugging%20Face%20Space-yellow.svg)](https://huggingface.co/spaces/miragea/miragea-voice-mcp)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![MCP](https://img.shields.io/badge/MCP-stdio-black.svg)](https://modelcontextprotocol.io)
+
+**tts-mcp-server is an open-source text-to-speech (TTS) MCP server that gives AI agents a voice.** It lets Claude Desktop, Claude Code, Cursor, OpenAI Codex, VS Code and Windsurf turn a script into a narration audio file (MP3, WAV, FLAC, Opus, AAC or PCM) plus matching SRT and WebVTT subtitles in one [Model Context Protocol](https://modelcontextprotocol.io) tool call. It also clones a voice from a reference audio URL, uses the voices saved in your account, and transcribes any local audio or video file into captions. Text-to-speech, voice cloning and speech recognition run on the [Miragea](https://miragea.ai) voice engine. Install it with one command, `uvx tts-mcp-server`; it needs only a `MIRAGEA_API_KEY` and is MIT licensed.
+
+**Install:** `uvx tts-mcp-server` · `pip install tts-mcp-server` · `docker run -i --rm -e MIRAGEA_API_KEY miragea/tts-mcp-server` · **Try it in the browser:** [live demo on Hugging Face Spaces](https://huggingface.co/spaces/miragea/miragea-voice-mcp) · **Source:** [github.com/RTY2345RR/miragea-voice-mcp](https://github.com/RTY2345RR/miragea-voice-mcp)
+
+> Formerly published as `miragea-voice-mcp`. The `miragea-voice-mcp` command is still installed as an alias, so existing configs keep working.
+
+<!-- mcp-name: io.github.RTY2345RR/tts-mcp-server -->
+
+![Terminal screenshot: installing the voiceover and captions MCP server with uvx from GitHub, printing the Claude Code config, and listing its 7 MCP tools (text-to-speech, voice cloning, transcription to SRT/VTT)](docs/images/voiceover-captions-mcp-server-terminal-demo.svg)
+
+```text
+You:    Turn script.txt into a calm voiceover with captions for a YouTube Short.
+Agent:  miragea_script_to_voiceover(script_file="script.txt", actor_id="…", tags=["calm"])
+        → ~/Miragea/my-short.mp3  ~/Miragea/my-short.srt  ~/Miragea/my-short.vtt
+```
+
+---
+
+## Contents
+
+- [How it works](#how-it-works)
+- [Features](#features)
+- [Quickstart (60 seconds)](#quickstart-60-seconds)
+- [Client setup: Claude Desktop, Claude Code, Cursor, Codex, VS Code, Windsurf](#client-setup)
+- [Tools reference](#tools-reference)
+- [Examples with real output](#examples)
+- [Example prompts](#example-prompts)
+- [Configuration](#configuration)
+- [How it compares](#how-it-compares)
+- [FAQ](#faq)
+- [Troubleshooting](#troubleshooting)
+- [Agent Skill](#companion-agent-skill)
+- [Development](#development)
+- [Links](#links)
+
+## How it works
+
+![Architecture diagram of the voiceover and captions MCP server: an AI agent such as Claude, Cursor or Codex calls tts-mcp-server over MCP stdio; the server calls the Miragea voice engine for text-to-speech, voice cloning and speech recognition, and writes MP3 audio plus SRT and WebVTT captions](docs/images/voiceover-captions-mcp-architecture-diagram.svg)
+
+1. Your AI agent (Claude Desktop, Claude Code, Cursor, OpenAI Codex, VS Code or Windsurf) calls a tool such as `miragea_script_to_voiceover` over the Model Context Protocol (stdio).
+2. The server checks the request against the live voice-engine capabilities (models, emotion tags, formats, text length) and adds an idempotency key.
+3. The [Miragea](https://miragea.ai) voice engine generates the narration (or clones a voice from your reference clip), then runs speech recognition on the new audio for timestamps.
+4. The server writes `.mp3` + `.srt` + `.vtt` side by side, with captions that keep your exact script wording, ready to import into your video editor.
+
+## Features
+
+- **Script → voiceover + captions in one call.** `miragea_script_to_voiceover` generates the narration, times captions by running Miragea speech recognition on the new audio, and writes `.mp3` + `.srt` + `.vtt` side by side, ready for CapCut, Premiere Pro, DaVinci Resolve, YouTube, TikTok, Reels and Shorts.
+- **Captions spelled like your script.** Recognition can mishear brand names ("Miragea" → "Mirage ear"). By default the server keeps the recognized *timing* but puts back your *exact script wording*, snapping cue breaks to sentence ends.
+- **Short-form friendly caption lengths.** `max_caption_chars` (default 42 for scripts) splits long cues and shares their time by length, so captions stay readable on vertical video.
+- **Two voice sources.** Use a voice already saved in your Miragea account (`actor_id`), or clone from a public reference audio URL (`reference_audio_url` + optional `reference_text`).
+- **Expressive or standard models, emotion tags, speed 0.25–4×.** Options are read live from `/capabilities`, and every argument is validated *before* a job is submitted.
+- **Subtitles for any audio or video file.** `miragea_transcribe` uploads mp3/wav/m4a/mp4/mov… and saves SRT, VTT, TXT or JSON (text, language, timed segments).
+- **No duplicate jobs on retry.** Every job carries an `Idempotency-Key`; network errors and 502/503/504 are retried with the *same* key, so a retry never creates a second job. Timeouts return the `task_id` so the agent resumes with `miragea_get_task` instead of resubmitting.
+- **Never overwrites files.** Existing outputs get `-2`, `-3`… suffixes.
+- **Secret-safe.** The key is read from the environment, never logged, never echoed in errors, never sent to the audio download host, and API redirects are not followed.
+- **Starts without a key.** Tool listing works with no key (handy for registries and inspectors); calls return a clear "set MIRAGEA_API_KEY" message.
+- **Works on MCP Python SDK 1.x and 2.x**, Python 3.10–3.13, macOS, Windows and Linux. Two dependencies: `mcp` and `httpx`.
+
+## Quickstart (60 seconds)
+
+1. **Get a voice-engine key.** The server uses [Miragea](https://miragea.ai) for voiceover, voice cloning and recognition. Sign in and create an API key at **[miragea.ai/workspace/api](https://miragea.ai/workspace/api)**. Setup guide: **Install https://miragea.ai/skills/miragea-audio/install.md**.
+2. **Install [uv](https://docs.astral.sh/uv/)** if you don't have it: `curl -LsSf https://astral.sh/uv/install.sh | sh` (macOS/Linux) or `powershell -c "irm https://astral.sh/uv/install.ps1 | iex"` (Windows).
+3. **Add the server to your client** (Claude Code shown; others below):
+
+```bash
+claude mcp add tts -s user -e MIRAGEA_API_KEY=<your-miragea-api-key> -- uvx tts-mcp-server
+```
+
+4. **Verify** (read-only, creates no job):
+
+```bash
+MIRAGEA_API_KEY=<your-miragea-api-key> uvx tts-mcp-server --check
+```
+
+Then ask your agent: *"List my Miragea voices, then read 'Welcome back to the channel!' in the first English one."*
+
+> Prefer pip? `pip install tts-mcp-server` and use `"command": "tts-mcp-server"` with no `args` in the snippets below. Prefer Docker? Use `"command": "docker"` with `"args": ["run", "-i", "--rm", "-e", "MIRAGEA_API_KEY", "-v", "/path/to/output:/data", "miragea/tts-mcp-server"]`.
+
+## Client setup
+
+Print any snippet with `uvx tts-mcp-server --print-config <client>` (`claude-desktop`, `cursor`, `claude-code`, `codex`, `vscode`, `windsurf`). Replace `<your-miragea-api-key>` and restart the client.
+
+### Claude Desktop
+
+Settings → Developer → Edit Config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows):
+
+```json
+{
+  "mcpServers": {
+    "tts": {
+      "command": "uvx",
+      "args": ["tts-mcp-server"],
+      "env": { "MIRAGEA_API_KEY": "<your-miragea-api-key>" }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add tts -s user -e MIRAGEA_API_KEY=<your-miragea-api-key> -- uvx tts-mcp-server
+```
+
+### Cursor
+
+`~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project) — same JSON as Claude Desktop.
+
+### OpenAI Codex (CLI and IDE extension)
+
+`~/.codex/config.toml`:
+
+```toml
+[mcp_servers.tts]
+command = "uvx"
+args = ["tts-mcp-server"]
+tool_timeout_sec = 900
+env = { MIRAGEA_API_KEY = "<your-miragea-api-key>" }
+```
+
+`tool_timeout_sec` matters: voiceover jobs can take longer than Codex's default tool timeout.
+
+### VS Code (Copilot agent mode)
+
+`.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "tts": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["tts-mcp-server"],
+      "env": { "MIRAGEA_API_KEY": "<your-miragea-api-key>" }
+    }
+  }
+}
+```
+
+### Windsurf
+
+`~/.codeium/windsurf/mcp_config.json` — same JSON as Claude Desktop.
+
+## Tools reference
+
+| Tool | What it does |
+| --- | --- |
+| `miragea_get_capabilities` | Live models (`expressive`, `standard`), emotion tags per model, formats, speed range, max characters per request, subtitle formats and upload limits. **Call first.** |
+| `miragea_list_voices` | Voices saved in your account (`actor_id`, `name`, `language`), paged; `search` finds a name across pages. |
+| `miragea_text_to_speech` | Text (or `text_file`) → audio file. Voice via `actor_id` **or** `reference_audio_url` (+ `reference_text`). Options: `model`, `tags`, `speed`, `format`, `language`, `output_path`, `wait`. |
+| `miragea_transcribe` | Local audio/video → subtitles in `srt`, `vtt`, `txt`, `json`; `max_caption_chars` for short cues. |
+| `miragea_script_to_voiceover` | Script → audio + captions (SRT + VTT by default). `caption_text="script"` (exact wording) or `"recognized"`; `captions=false` for audio only; `name`, `output_dir`. |
+| `miragea_get_task` | Check or resume any job by `task_id`; with `wait=true` it saves the audio or subtitles. |
+| `miragea_list_tasks` | Recent jobs, newest first. |
+
+Every generation tool returns `task_id`, `status` and the `idempotency_key` it used, plus the saved file paths.
+
+## Examples
+
+Real outputs from this server (Miragea voice engine), committed in [`examples/`](https://github.com/RTY2345RR/miragea-voice-mcp/tree/main/examples). Voices are cloned from [CMU ARCTIC](http://www.festvox.org/cmu_arctic/) reference clips (licensed free for any use); the audiobook clip is from [LibriSpeech](https://www.openslr.org/12) (CC BY 4.0).
+
+| Example | Prompt to your agent | Tools | Output |
+| --- | --- | --- | --- |
+| [YouTube voiceover with SRT](https://github.com/RTY2345RR/miragea-voice-mcp/tree/main/examples/youtube-voiceover-srt) | "Read `script.txt` as a YouTube intro in a clear male voice and give me SRT captions." | `miragea_text_to_speech` → `miragea_transcribe` | [MP3](https://github.com/RTY2345RR/miragea-voice-mcp/raw/main/examples/youtube-voiceover-srt/youtube-intro.mp3) · [SRT](https://github.com/RTY2345RR/miragea-voice-mcp/blob/main/examples/youtube-voiceover-srt/youtube-intro.srt) |
+| [Two-voice dialogue](https://github.com/RTY2345RR/miragea-voice-mcp/tree/main/examples/two-voice-dialogue) | "Make a two-line dialogue: one male, one female voice, then join them with captions." | `miragea_text_to_speech` ×2 (voice cloning) | [MP3](https://github.com/RTY2345RR/miragea-voice-mcp/raw/main/examples/two-voice-dialogue/dialogue.mp3) · [SRT](https://github.com/RTY2345RR/miragea-voice-mcp/blob/main/examples/two-voice-dialogue/dialogue.srt) |
+| [Transcribe audio to captions](https://github.com/RTY2345RR/miragea-voice-mcp/tree/main/examples/transcribe-to-captions) | "Create SRT and VTT subtitles for `audiobook-clip.flac`." | `miragea_transcribe` | [SRT](https://github.com/RTY2345RR/miragea-voice-mcp/blob/main/examples/transcribe-to-captions/audiobook-clip.srt) · [VTT](https://github.com/RTY2345RR/miragea-voice-mcp/blob/main/examples/transcribe-to-captions/audiobook-clip.vtt) |
+
+Transcription output (`audiobook-clip.srt`), with words kept whole across cues:
+
+```srt
+1
+00:00:00,480 --> 00:00:01,987
+He hoped there would be stew for
+
+2
+00:00:01,987 --> 00:00:03,987
+dinner, turnips and carrots, and
+
+3
+00:00:03,987 --> 00:00:06,063
+bruised potatoes and fat mutton
+```
+
+## Example prompts
+
+- "Make a 30-second product-ad voiceover from `ad.txt` with my *Nova* voice, happy tone, 1.1× speed, and give me SRT + VTT with short captions."
+- "Clone the voice at `https://example.com/me.wav` (it says: 'Hi, I'm Sam and this is my test.') and narrate `intro.md` as WAV."
+- "Create subtitles for `~/Videos/vlog.mp4` as SRT and VTT."
+- "That voiceover timed out — resume task `…` and save it to `~/Desktop/episode-3.mp3`."
+- "What models and emotion tags does my Miragea account have, and how many characters can I send per request?"
+
+## Configuration
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `MIRAGEA_API_KEY` | — (required for calls) | Your key from [miragea.ai/workspace/api](https://miragea.ai/workspace/api). |
+| `MIRAGEA_OUTPUT_DIR` | `~/Miragea` | Where relative output paths and default file names go. Absolute paths are used as given. |
+| `MIRAGEA_BASE_URL` | `https://miragea.ai/v1` | API root including `/v1` (for private deployments). |
+| `MIRAGEA_WAIT_TIMEOUT` | `600` | Max seconds a tool waits for a job before returning its `task_id`. |
+| `MIRAGEA_HTTP_TIMEOUT` | `60` | Per-request HTTP timeout in seconds. |
+
+## How it compares
+
+Honest snapshot from each project's public README (November 2026). "–" means not offered or not documented.
+
+| | **This server** | [elevenlabs-mcp](https://github.com/elevenlabs/elevenlabs-mcp) (local) | [AllVoiceLab-MCP](https://github.com/allvoicelab/AllVoiceLab-MCP) | [better-tts-mcp](https://github.com/CatVinci-Studio/better-tts-mcp) |
+| --- | --- | --- | --- | --- |
+| Status | Active | Deprecated in favor of ElevenLabs' hosted MCP | Active | Active |
+| Voice engine | Miragea | ElevenLabs API | AllVoiceLab API | Microsoft Edge read-aloud (unofficial, no key) |
+| One-command install | `uvx tts-mcp-server` | `uvx elevenlabs-mcp` | `uvx allvoicelab-mcp` | `uvx better-tts-mcp` |
+| Required config | 1 env var | 1 env var | Key **and** matching region domain | None |
+| Ready snippets for Claude Desktop / Claude Code / Cursor / Codex / VS Code / Windsurf | All six + `--print-config` | Claude Desktop + `--print` helper | Claude Desktop, Cursor | Claude Desktop, Claude Code |
+| Voice cloning from a sample | Reference audio URL | Yes (voice library) | Yes | – |
+| Subtitles from your own audio/video (speech) | SRT, VTT, TXT, JSON | Speech-to-text (text) | OCR of burned-in subtitles | – |
+| Script → audio **+ captions** in one call | Yes | – | – | Audio + SRT |
+| Captions keep exact script spelling | Yes | – | – | Yes (from TTS) |
+| No duplicate jobs on retry (idempotency keys) + resume by task ID | Yes | – | – | – |
+
+Where the others are ahead: ElevenLabs and AllVoiceLab cover more audio tasks (sound effects, voice changer, dubbing, agents), and better-tts-mcp needs no key and offers batch and multi-voice synthesis. This server stays focused on the video-creator loop of **script → voiceover → captions** and does that one loop end to end.
+
+## FAQ
+
+### What is a TTS MCP server?
+A TTS (text-to-speech) MCP server is a small program that exposes speech synthesis as tools over the Model Context Protocol, so an AI agent such as Claude or Cursor can turn text into an audio file on request. tts-mcp-server adds voice cloning, speech-to-text subtitles and a one-call script → voiceover + SRT/VTT workflow on top.
+
+### How do I install a text to speech MCP server in Claude Code?
+Run `claude mcp add tts -s user -e MIRAGEA_API_KEY=<your-miragea-api-key> -- uvx tts-mcp-server`, then ask Claude to "read this paragraph aloud and save it as MP3". Use `uvx tts-mcp-server --print-config <client>` for Claude Desktop, Cursor, Codex, VS Code or Windsurf.
+
+### Is there a free text to speech MCP server?
+The server itself is free, open-source software (MIT). Speech is generated by the Miragea voice engine, so you need a Miragea API key. If you need a keyless option, [better-tts-mcp](https://github.com/CatVinci-Studio/better-tts-mcp) uses Microsoft Edge read-aloud, and [kokoro-tts-mcp](https://github.com/mberg/kokoro-tts-mcp) runs a local model; neither does voice cloning or subtitles from your own audio.
+
+### Is this an alternative to the ElevenLabs MCP server?
+Yes, for the voiceover use case. Like [elevenlabs-mcp](https://github.com/elevenlabs/elevenlabs-mcp) it installs with `uvx` and gives agents text-to-speech and voice cloning; unlike it, one tool call returns the audio together with SRT/VTT captions that keep your exact script wording. ElevenLabs covers more audio tasks (sound effects, voice changer, conversational agents); see [How it compares](#how-it-compares).
+
+### How do I add text-to-speech to Claude Desktop?
+Add the `tts` block from [Claude Desktop](#claude-desktop) to `claude_desktop_config.json`, put your Miragea API key in `env`, and restart Claude. Claude can then call `miragea_text_to_speech` and save MP3 files to `~/Miragea`.
+
+### How do I generate SRT subtitles from a video with an AI agent?
+Ask the agent to run `miragea_transcribe` on the file (for example, *"make SRT and VTT subtitles for ~/Videos/clip.mp4"*). The server uploads it to Miragea speech recognition and writes `clip.srt` / `clip.vtt`.
+
+### Can an MCP server make a voiceover with matching captions for YouTube Shorts or TikTok?
+Yes. `miragea_script_to_voiceover` returns the audio plus SRT/VTT captions timed to that audio, with cues capped at 42 characters by default for vertical video. Import both into CapCut, Premiere Pro or DaVinci Resolve.
+
+### Does it support voice cloning?
+Yes. Pass `reference_audio_url` (a public http(s) link to a clean sample) and, ideally, `reference_text` with the exact words spoken in it. Supplying the exact text gives the most faithful clone; if you omit it, Miragea recognizes it automatically. Only clone voices you have the right to use.
+
+### Does it work with Cursor, Claude Code and OpenAI Codex?
+Yes, with any MCP client that supports stdio servers. Run `uvx tts-mcp-server --print-config cursor` (or `claude-code`, `codex`, `vscode`, `windsurf`, `claude-desktop`) for a ready snippet.
+
+### Which audio formats can I export?
+MP3 (default), WAV, FLAC, Opus, AAC and PCM. Subtitles: SRT, WebVTT, plain text, and JSON with timed segments.
+
+### Can I use it without an API key or with another TTS engine?
+No. Miragea is the only voice engine; there is no hidden fallback. Without a key the server still starts and lists its tools, and every call explains how to add the key.
+
+### Is my API key safe?
+The key stays in your local MCP config or environment. The server never prints or logs it, redacts it from errors, sends it only to the Miragea API root (redirects are refused), and never sends it to the audio download URL.
+
+### What happens if a long voiceover times out?
+The job keeps running on Miragea. The tool returns the `task_id`; ask the agent to call `miragea_get_task` with `wait=true` to download the result. Don't resubmit, because that would create a duplicate job.
+
+### Can I use it in Python scripts or n8n instead of chat?
+Any MCP-capable runtime works. For plain scripts, call the Miragea REST API directly ([guide](https://miragea.ai/v1/guide), [OpenAPI schema](https://miragea.ai/v1/schema)).
+
+## Troubleshooting
+
+| Symptom | Fix |
+| --- | --- |
+| `MIRAGEA_API_KEY is not set` | Add the key to the server's `env` block (not your shell profile, for GUI clients) and fully restart the client. |
+| `HTTP 401 invalid_api_key` | The key is wrong or revoked. Create a new one at [miragea.ai/workspace/api](https://miragea.ai/workspace/api). Run `uvx tts-mcp-server --check`. |
+| `HTTP 403` | The account has no API access right now; check it in your Miragea account. `cloudflare_blocked` means a proxy or VPN is being challenged; try another network. |
+| `HTTP 429` | Rate-limited or an account limit was reached. Check your Miragea account, or wait and retry. |
+| `Text is N characters but this account allows M` | Split the script into parts under `audio.max_text_length` and generate them one by one. |
+| `wait_timeout` | The job is still running. Use `miragea_get_task` with the returned `task_id`. Raise `MIRAGEA_WAIT_TIMEOUT` and your client's tool timeout (Codex: `tool_timeout_sec`). |
+| Client tool call times out first | Call with `wait=false`, then poll with `miragea_get_task`. |
+| `spawn uvx ENOENT` | The GUI app can't find `uvx`. Use its absolute path (`which uvx` / `where uvx`) as `command`. |
+| `Tag(s) … are not available` | Tags are per model. List them with `miragea_get_capabilities`. |
+| `reference_audio_url must be a public http(s) URL` | Miragea downloads the sample server-side. Upload it somewhere public (not `localhost`, not a file path). |
+| Where are my files? | `~/Miragea` by default, or `MIRAGEA_OUTPUT_DIR`. Each tool returns the exact path. |
+
+Logs go to stderr, which your client keeps (Claude Desktop on macOS: `~/Library/Logs/Claude/mcp-server-tts.log`).
+
+## Companion Agent Skill
+
+[`skills/miragea-voiceover/SKILL.md`](skills/miragea-voiceover/SKILL.md) is an [Agent Skill](https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills) that teaches Claude a script-to-voiceover workflow on top of these tools: tightening a script for speech, choosing a voice and tone, confirming long jobs first, and delivering audio and captions for each platform. Copy the folder into `~/.claude/skills/` (Claude Code) or upload it as a skill in Claude. It is also published on its own in [RTY2345RR/miragea-agent-skills](https://github.com/RTY2345RR/miragea-agent-skills) with install steps for Claude Code, Codex and Cursor.
+
+## Development
+
+```bash
+git clone https://github.com/RTY2345RR/miragea-voice-mcp && cd miragea-voice-mcp
+uv venv && uv pip install -e ".[dev]"
+pytest                                   # offline; HTTP is mocked
+npx @modelcontextprotocol/inspector uvx --from . tts-mcp-server
+```
+
+The server wraps only the documented Miragea endpoints: `GET /capabilities`, `GET /actors`, `POST /audio/generations`, `POST /subtitles/recognitions`, `GET /tasks/{id}`, `GET /tasks` ([API guide](https://miragea.ai/v1/guide)). VTT and short-cue splitting are local formatting of Miragea's timed segments.
+
+## Links
+
+- GitHub: https://github.com/RTY2345RR/miragea-voice-mcp
+- Live demo (Hugging Face Space): https://huggingface.co/spaces/miragea/miragea-voice-mcp
+- Agent Skills: https://github.com/RTY2345RR/miragea-agent-skills
+- Miragea API keys: https://miragea.ai/workspace/api
+- PyPI: https://pypi.org/project/tts-mcp-server/
+- Docker Hub: https://hub.docker.com/r/miragea/tts-mcp-server
+
+## License
+
+[MIT](LICENSE). "Miragea" is the voice engine this server connects to (voiceover, voice cloning, speech recognition). Use cloned voices only with the speaker's consent.

tts_mcp_server-0.1.1/PUBLISHING.md

@@ -0,0 +1,143 @@
+# Publishing checklist
+
+Everything below assumes the GitHub repository is **`github.com/RTY2345RR/miragea-voice-mcp`**.
+If it ever moves to another owner, replace
+`RTY2345RR/miragea-voice-mcp` and `io.github.RTY2345RR/` with your owner in: `server.json` (`name`,
+`repository.url`), `README.md` (the `mcp-name:` comment and the links), `pyproject.toml`
+(`[project.urls]`), `llms.txt`, `CHANGELOG.md`, `glama.json` (`maintainers`) and
+`src/miragea_voice_mcp/client.py` (`USER_AGENT`). Then run `pytest`, which checks that the
+README `mcp-name` matches `server.json`.
+
+## 1. GitHub repository
+
+**Description** (paste into *About*):
+
+> Voiceover & captions MCP server for AI agents: turn a script into narration + SRT/VTT subtitles from Claude, Cursor and Codex. Voice cloning, emotion tags, transcription. Miragea voice engine.
+
+**Website:** `https://huggingface.co/spaces/miragea/miragea-voice-mcp` (live demo)
+
+**Topics** (20, GitHub's maximum):
+
+```
+mcp  mcp-server  model-context-protocol  text-to-speech  tts  voiceover  ai-voice
+voice-cloning  subtitles  srt  webvtt  captions  speech-to-text  transcription
+claude  claude-code  cursor  codex  video-editing  youtube-shorts
+```
+
+CLI: `gh repo edit RTY2345RR/miragea-voice-mcp --description "…" --homepage https://huggingface.co/spaces/miragea/miragea-voice-mcp --add-topic mcp --add-topic mcp-server …` (one `--add-topic` per topic).
+
+**Release:** tag `v0.1.0`, title "v0.1.0 — script to voiceover + captions", and paste the CHANGELOG section as the body.
+
+Also: enable Discussions, upload a social preview image (1280×640) showing the script → mp3 + srt flow, and pin the repo on the profile.
+
+## 2. PyPI (`tts-mcp-server`)
+
+Recommended: **trusted publishing** (no token stored anywhere).
+
+1. Sign in at pypi.org → *Your account → Publishing → Add a new pending publisher*:
+   project `tts-mcp-server`, owner `RTY2345RR`, repo `miragea-voice-mcp`, workflow `publish.yml`, environment `pypi`.
+2. On GitHub: *Settings → Environments → New environment* named `pypi`.
+3. Run *Actions → Publish → Run workflow* (or add a `release: published` trigger to `.github/workflows/publish.yml`). It builds the package, uploads it to PyPI, then publishes to the MCP Registry (step 3).
+
+Manual alternative:
+
+```bash
+uv build                 # dist/tts_mcp_server-0.1.1-py3-none-any.whl + .tar.gz
+uvx twine check dist/*
+uvx twine upload dist/*  # needs a PyPI API token
+```
+
+Verify: `uvx tts-mcp-server --version` on a clean machine.
+
+## 3. Official MCP Registry (registry.modelcontextprotocol.io)
+
+The registry checks that the PyPI README contains `<!-- mcp-name: io.github.RTY2345RR/tts-mcp-server -->` (already in `README.md`), so publish to PyPI first.
+
+```bash
+# install the publisher CLI (macOS: brew install mcp-publisher)
+curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
+sudo mv mcp-publisher /usr/local/bin/
+
+cd miragea-voice-mcp
+mcp-publisher login github        # sign in as GitHub user `RTY2345RR` (io.github.RTY2345RR namespace)
+mcp-publisher publish             # reads ./server.json
+curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.RTY2345RR/tts-mcp-server"
+```
+
+CI does the same with `mcp-publisher login github-oidc` after each release. For every new version, bump `version` in `pyproject.toml`, `src/miragea_voice_mcp/__init__.py` and both places in `server.json` (the tests enforce this).
+
+Optional: owning `miragea.ai` allows the namespace `ai.miragea/voice` via DNS verification (`mcp-publisher login dns --domain miragea.ai …`). Change `name` and the README `mcp-name` together if you switch.
+
+Many directories (PulseMCP and others) import from the official registry, so this step also feeds them.
+
+## 4. Smithery (smithery.ai)
+
+1. Sign in at https://smithery.ai with the GitHub account that owns the repo.
+2. Choose **Publish / Add server** → select `RTY2345RR/miragea-voice-mcp`.
+3. Smithery reads `smithery.yaml` (stdio; config field `mirageaApiKey` maps to `MIRAGEA_API_KEY`) and builds with the root `Dockerfile`. If the UI asks for a deployment type, choose local/stdio.
+4. After the build passes, open the server page, check that all 7 tools are listed (they list without a key), and add the description, the demo homepage and the topics.
+
+## 5. Glama (glama.ai/mcp/servers)
+
+1. Go to https://glama.ai/mcp/servers → **Add Server** → submit `https://github.com/RTY2345RR/miragea-voice-mcp`.
+2. `glama.json` lists `RTY2345RR` as maintainer, so sign in with that GitHub account and **Claim** the server.
+3. Glama builds the `Dockerfile` and runs an introspection check. It passes without a key because the server starts and lists tools without one. In the server's admin settings, set `MIRAGEA_API_KEY` as a placeholder or a test key if you want the "tested" badge.
+4. Copy the score badge for the awesome-mcp-servers PR:
+   `[![RTY2345RR/miragea-voice-mcp MCP server](https://glama.ai/mcp/servers/RTY2345RR/miragea-voice-mcp/badges/score.svg)](https://glama.ai/mcp/servers/RTY2345RR/miragea-voice-mcp)`
+
+## 6. mcp.so
+
+1. Open https://mcp.so and click **Submit** (top navigation).
+2. Type: MCP Server. Name: `Voiceover & Captions MCP (Miragea voice engine)`. URL: the GitHub repo.
+3. Description: the GitHub description above. Tags: text-to-speech, voiceover, subtitles, captions, voice-cloning.
+4. Server config: paste the Claude Desktop JSON from the README.
+   Fallback if the form is unavailable: open an issue in mcp.so's GitHub repository with the same details.
+
+## 7. PulseMCP
+
+PulseMCP ingests the official registry, so the listing usually appears within about a week of step 3. To speed it up or correct details, use https://www.pulsemcp.com/submit with the GitHub URL and the description above.
+
+## 8. awesome-mcp-servers (punkpeye) pull request
+
+Do this after Glama lists the server, because entries there carry the Glama score badge.
+
+```bash
+gh repo fork punkpeye/awesome-mcp-servers --clone && cd awesome-mcp-servers
+git checkout -b add-miragea-voice-mcp
+```
+
+In `README.md`, under **🎧 Text-to-Speech**, insert this line in alphabetical order (after `mberg/kokoro-tts-mcp`, before `transcribe-app/mcp-transcribe`):
+
+```markdown
+- [RTY2345RR/miragea-voice-mcp](https://github.com/RTY2345RR/miragea-voice-mcp) [![RTY2345RR/miragea-voice-mcp MCP server](https://glama.ai/mcp/servers/RTY2345RR/miragea-voice-mcp/badges/score.svg)](https://glama.ai/mcp/servers/RTY2345RR/miragea-voice-mcp) 🎖️ 🐍 ☁️ 🍎 🪟 🐧 - Voiceover & captions for AI agents: script to narration plus SRT/VTT subtitles, voice cloning from a reference URL, emotion tags, and subtitles for any audio or video file (Miragea voice engine).
+```
+
+```bash
+git commit -am "Add RTY2345RR/miragea-voice-mcp to Text-to-Speech"
+git push -u origin add-miragea-voice-mcp
+gh pr create --repo punkpeye/awesome-mcp-servers --title "Add tts-mcp-server (text-to-speech, voiceover + subtitles)" \
+  --body "Voiceover & captions MCP server (Python, stdio, MIT, Miragea voice engine). Script → voiceover + SRT/VTT captions, voice cloning, transcription. Listed on Glama."
+```
+
+Their CONTRIBUTING notes that PRs opened by an automated agent can append `🤖🤖🤖` to the title for a fast-tracked review. Use it only when an agent actually opens the PR. Disclose that you maintain the project, since 🎖️ marks an official implementation.
+
+## 9. More places worth a listing (optional)
+
+- **Anthropic Agent Skills:** publish `skills/miragea-voiceover` in the README and to skill directories such as skillsmp.com, and add it to community `awesome-claude-skills` lists via PR.
+- **MCP directories:** mcpservers.org, mcpmarket.com, cursor.directory (MCP section), LobeHub MCP marketplace. Each has a "Submit" form; reuse the description above.
+- **Docker MCP Catalog** (`docker/mcp-registry` PR): uses the `Dockerfile` in this repo.
+
+## Before each release
+
+```bash
+pytest
+uv build && uvx twine check dist/*
+python -c "import json;d=json.load(open('server.json'));assert len(d['description'])<=100"
+```
+
+Then optionally run a real smoke test with a key, using a short test line:
+
+```bash
+MIRAGEA_API_KEY=… uvx tts-mcp-server --check   # read-only
+# in your MCP client: "Use miragea_text_to_speech to say 'Hi' with my first voice"
+```