{
  "markdown": "# Text to Speech MCP Server\n\n<!-- mcp-name: io.github.Engr-FaizanAli/text-to-speech -->\n\n[![PyPI version](https://img.shields.io/pypi/v/text-to-speech-mcp.svg)](https://pypi.org/project/text-to-speech-mcp/)\n[![Downloads](https://img.shields.io/pypi/dm/text-to-speech-mcp.svg)](https://pypi.org/project/text-to-speech-mcp/)\n[![Python versions](https://img.shields.io/pypi/pyversions/text-to-speech-mcp.svg)](https://pypi.org/project/text-to-speech-mcp/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![CI](https://github.com/Engr-FaizanAli/text-to-speech-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Engr-FaizanAli/text-to-speech-mcp/actions/workflows/ci.yml)\n\n**Give your AI assistant a voice — locally, with no API key, no account, and no\ncloud service.**\n\nText to Speech is an open-source Model Context Protocol (MCP) server that lets\nAI assistants read text aloud on the user's computer. It uses the speech\nsynthesizer already present on the host operating system, so nothing you ask it\nto say ever leaves your machine.\n\nRuns on **Windows, macOS, and Linux**. Install is one line:\n\n```text\nuvx text-to-speech-mcp\n```\n\nThe server exposes one model-controlled tool:\n\n```text\nspeak_text(text: string)\n```\n\nUse it for user-provided text, assistant answers, accessibility workflows, or\nspoken progress updates while an agent works.\n\n### Why this one\n\nMost text-to-speech MCP servers wrap a cloud API, which means an account, a\nkey, per-character billing, and your text leaving the machine. This one uses\nthe speech engine your operating system already ships, so it works offline,\ncosts nothing, and keeps text local — which matters if you work anywhere that\nregulates where data may go.\n\nIt also ships an [agent narration skill](#agent-narration-skill), so an\nassistant knows *how* to narrate, not just that it can.\n\n## Features\n\n- Local playback through the platform's built-in synthesizer by default:\n  Windows SAPI, macOS `say`, or `espeak-ng` on Linux.\n- No cloud API and no API key for the default setup.\n- FIFO playback: concurrent requests are spoken one at a time, in order.\n- Blocking tool completion: each call returns after its audio finishes.\n- Bounded input and queue sizes to prevent unbounded resource use.\n- Temporary generated WAV files are removed after playback by default.\n- Standard MCP `stdio` transport through the official Python SDK.\n- Optional Piper, Transformers MMS, and local HTTP backends for advanced users.\n\n> The MCP server source is open source under the MIT License. Windows SAPI and\n> the macOS `say` command are proprietary components of their operating\n> systems; they are not open-source speech engines. `espeak-ng` is separately\n> licensed open-source software.\n\n## Requirements\n\n- Python 3.10 or newer.\n- An MCP client that supports stdio MCP servers.\n- `uv`/`uvx` is recommended for package-based MCP installation.\n\nPer platform, for the zero-configuration default:\n\n| Platform | Synthesis | Playback | Extra install |\n| --- | --- | --- | --- |\n| Windows 10/11 | SAPI via PowerShell | `System.Media.SoundPlayer` | None |\n| macOS | `say` | `afplay` | None |\n| Linux / other Unix | `espeak-ng` or `espeak` | `aplay`, `paplay`, `play`, or `ffplay` | `espeak-ng` and one player |\n\nOn Debian or Ubuntu that is typically:\n\n```bash\nsudo apt install espeak-ng alsa-utils\n```\n\nSet `TEXT_TO_SPEECH_BACKEND` or `TEXT_TO_SPEECH_PLAYER` to override either\nchoice. If a required command is missing, the server reports which one and how\nto install it rather than failing silently.\n\n## Install\n\nConfigure an MCP client to run the published PyPI package:\n\n```text\nuvx text-to-speech-mcp\n```\n\nFor MCP clients that accept command-based server configuration, use:\n\n```toml\ncommand = \"uvx\"\nargs = [\"text-to-speech-mcp\"]\nstartup_timeout_sec = 30\ntool_timeout_sec = 300\nenabled = true\n```\n\nSome clients use TOML, JSON, or a graphical settings page. Use\n`uvx text-to-speech-mcp` as the server command and restart the client after\nchanging its configuration.\n\n### Install from source\n\n```powershell\ngit clone https://github.com/Engr-FaizanAli/text-to-speech-mcp.git\ncd text-to-speech-mcp\npython -m pip install .\n```\n\nThen configure the client to run `text-to-speech-mcp` directly.\n\n## Prompt Examples\n\nRead arbitrary text:\n\n```text\nUse the Text to Speech tool to read aloud: The deployment completed successfully.\n```\n\nRead the final answer:\n\n```text\nUse the Text to Speech tool to read your final response aloud before displaying it.\n```\n\nRead visible intermediate progress updates in order:\n\n```text\nUse the text_to_speech MCP server's speak_text tool for spoken progress updates.\n\nFor every meaningful intermediate update that you display to me:\n1. Call speak_text with the exact update text you are about to display.\n2. Wait for the call to finish before producing or speaking the next update.\n3. Then display the same update in text.\n\nAlso call speak_text with the exact final answer before displaying it. Never\nnarrate hidden reasoning, chain-of-thought, secrets, credentials, raw tool\noutput, terminal logs, or source code unless I explicitly ask you to read that\ncontent aloud. Do not invoke speech calls in parallel. If the tool is\nunavailable, continue normally in text and report the failure once.\n```\n\nThe `text_to_speech` portion is an example client-side server name. Clients may\ndisplay a different namespace while keeping the tool name `speak_text`.\n\n## Tool Contract\n\n| Field | Value |\n| --- | --- |\n| Tool name | `speak_text` |\n| Input | `text`, required string, 1-50,000 characters |\n| Result | Completion message after local playback finishes |\n| Ordering | FIFO, one active playback at a time |\n| Queue limit | 32 pending requests |\n| Network use with a built-in backend | None |\n\nThe tool is model-controlled under MCP. The user decides when to ask the model\nto call it, and the MCP client may show or require approval for tool calls.\n\n## Privacy\n\nWith any of the built-in backends, text is passed from the MCP client to a local\nPython process and then to the operating system's speech components. It is not\nsent to this project, an external API, or a cloud TTS provider. Generated WAV\nfiles are written to a `text-to-speech-mcp` directory inside the system\ntemporary directory (`%TEMP%` on Windows, `/tmp` on macOS and Linux) and\ndeleted after playback unless `TEXT_TO_SPEECH_KEEP_AUDIO=true` is set.\n\nThe `http` backend is the exception: whether text leaves the machine depends\nentirely on the endpoint you configure.\n\nDo not ask an AI assistant to speak secrets, credentials, private keys, hidden\nreasoning, or sensitive tool output.\n\n## Optional Backends\n\nThe default requires no configuration. `TEXT_TO_SPEECH_BACKEND` is unset and the\nserver selects `sapi`, `say`, or `espeak` to match the host platform.\n\nTo pin one explicitly, or to use a backend that is not built into the OS, set\n`TEXT_TO_SPEECH_BACKEND` to `sapi`, `say`, `espeak`, `piper`,\n`transformers_mms`, or `http`. The last three require their own local model,\nbinary, Python dependencies, or endpoint. `TEXT_TO_SPEECH_FALLBACK_BACKEND`\nnames a second backend to try if the first fails. See\n[backend configuration](https://github.com/Engr-FaizanAli/text-to-speech-mcp/blob/main/CONFIGURATION.md).\n\n## Agent Narration Skill\n\nA speech tool alone does not tell an assistant *when* or *how* to speak. Left to\nimprovise, agents narrate hidden reasoning, skip the parts you actually needed,\nor read a paraphrase instead of what is on screen.\n\n[`skills/project-tts-responder/SKILL.md`](skills/project-tts-responder/SKILL.md)\nis a ready-made narration policy built on `speak_text`. Copy it into your\nproject's `.claude/skills/` directory:\n\n| Mode | Behaviour |\n| --- | --- |\n| **Batch** (default) | One playback at the end of a turn, covering every visible update plus the final answer |\n| **Streaming** | Narrate each update as it appears — good for demos and walkthroughs |\n| **Read on request** | Read a named file or block of text verbatim |\n\nIt also handles the parts that are easy to get wrong:\n\n- **Interactive questions are narrated *before* the picker opens.** An\n  interactive question tool is itself the pause, and its options live in the\n  tool's parameters rather than in visible text — so any rule that narrates\n  \"once the options are visible\" fires only after the user has already\n  answered. This is the most common way narration silently fails.\n- Speaks exactly what is on screen, never a paraphrase.\n- Never speaks hidden reasoning, secrets, credentials, or raw tool output.\n- One playback call per turn, never parallel, with defined behaviour when a\n  call fails.\n\nThe skill applies when you ask for audio. To make a project narrate every\nresponse, say so in that project's own agent instructions — for example\n\"narrate every response in Batch mode unless I opt out\".\n\n## MCP Compatibility\n\n- MCP transport: `stdio`\n- MCP tool implementation: official Python MCP SDK\n- Registry metadata: `server.json` using the 2025-12-11 schema\n- Package registry: PyPI\n- Registry ownership marker: this README's `mcp-name` comment\n- Registry namespace: `io.github.Engr-FaizanAli/text-to-speech`\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n",
  "bytes": 9190,
  "sha": "fe95ecf6b7d80ebbd4b29c0d40d0235e8e08d69cec8a49d04f7323ca00020b6c",
  "repo_slug": "engr-faizanali/text-to-speech-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_engr_faizanali_text_to_speech_c341751f/readme"
}