ElevenLabs Audio MCP for ChatGPT

A small, self-hosted MCP app that lets ChatGPT turn text into ElevenLabs speech and return a playable, downloadable MP3 inside the conversation.

Each person deploys their own private instance and supplies their own ElevenLabs API key and preferred voice ID. The key stays in Railway and is never sent to ChatGPT or the audio widget.

This is an independent, community-built project. It is not affiliated with or endorsed by ElevenLabs or OpenAI.

What it includes

• generate_speech: creates temporary MP3 audio with an ElevenLabs voice.
• render_audio: displays an already-generated MP3 without calling ElevenLabs or consuming more credits.
• list_voices: searches the voices available to the deployer's account.
• get_preferred_voice: checks whether the person has already chosen a default voice.
• save_preferred_voice: validates and saves a voice after the person chooses it in chat.
• A compact audio player rendered through a lightweight, standards-based MCP Apps JSON-RPC bridge.
• A native temporary MP3 resource plus a direct signed link as a non-widget fallback when a host cannot initialize the widget.
• Short-lived, signed audio URLs.
• A secret, unguessable MCP path to protect the deployer's ElevenLabs credits.
• A Railway health check and configuration-as-code file.
• No analytics, database, user accounts, or permanent audio storage.

Natural speech prompting

The MCP gives ChatGPT server-wide guidance based on ElevenLabs' official speech prompting recommendations. Before generating audio, the model is instructed to:

• preserve the user's meaning, language, names, facts, and requested wording;
• shape ordinary prose into natural spoken rhythm with conversational phrasing and punctuation;
• write numbers, dates, symbols, abbreviations, URLs, and units as they should be pronounced;
• use only a few context-appropriate Eleven v3 audio tags when they improve the delivery;
• use punctuation, em dashes, or ellipses for Eleven v3 pauses instead of unsupported SSML break tags;
• keep quotations, legal text, code, and explicitly verbatim readings faithful.

Eleven v3 is the default because it offers the most expressive delivery controls. A caller can still request another supported model, and a Railway deployment can change the default through ELEVENLABS_MODEL_ID.

Deploy on Railway

The public template should define these service variables:

Variable	Required	Template value
ELEVENLABS_API_KEY	Yes	Ask the person deploying the template
MCP_PATH_SECRET	Yes	Generate with ${{ secret(48) }}
ELEVENLABS_VOICE_ID	Yes	Ask the person deploying the template
ELEVENLABS_MODEL_ID	No	eleven_v3
AUDIO_TTL_SECONDS	No	900
DATA_DIR	No	Not needed on Railway; attached volumes are detected automatically

Create the Railway template

1. Publish this repository on GitHub.
2. In Railway, create a project from the repository and enable public HTTP networking.
3. Add ELEVENLABS_API_KEY and ELEVENLABS_VOICE_ID as required template variables, both with empty values that the person deploying must fill in.
4. Add MCP_PATH_SECRET with the template function ${{ secret(48) }}.
5. Recommended: attach a small volume at /data. Railway exposes its path automatically, so the person deploying the template does not need to configure it.
6. Generate a template from the project and publish it.
7. Copy Railway's template code into the Deploy button in this README.

Railway reads railway.json, runs the TypeScript build, starts the server, and checks /health before completing the deployment.

Connect it to ChatGPT

After deployment, construct the private MCP URL:

https://YOUR-RAILWAY-DOMAIN/YOUR-MCP_PATH_SECRET/mcp

Then:

1. Enable Developer Mode in ChatGPT settings.
2. Create a new developer-mode app/connector.
3. Paste the private MCP URL above.
4. Add the app to a new conversation.
5. The voice entered during deployment is already the default. You can still try: “Help me choose another ElevenLabs voice and remember my choice.” The model can list the voices, ask which one you prefer, and save it after you answer.
6. Later, simply ask: “Read this aloud: Hello world.” The saved voice is used automatically.

The connector uses OpenAI's decoupled data/render pattern. ChatGPT first calls generate_speech, waits until the MP3 is ready, and then calls the fast render_audio tool to mount the player. Repeating render_audio does not regenerate the speech or spend more ElevenLabs credits. The player uses a very small, dependency-free MCP Apps handshake so hosts have less widget code to initialize. Widget rendering still depends on the ChatGPT client and is not guaranteed on every device; the signed MP3 resource and direct link remain available as fallbacks.

Keep the full MCP URL private. Anyone who obtains it could consume the ElevenLabs credits attached to that deployment. Rotate MCP_PATH_SECRET immediately if the URL is exposed.

The saved preference belongs to the deployment, not to a ChatGPT account. This is ideal for the intended one-person-per-deployment model. If several people share one deployment, they will also share its preferred voice.

Run locally

Requirements: Node.js 24 LTS and an ElevenLabs API key with Text to Speech and Voices read permissions.

Copy-Item .env.example .env
npm install
npm run dev

Edit .env before starting. The local MCP URL will be:

http://localhost:3000/YOUR-MCP_PATH_SECRET/mcp

ChatGPT requires a public HTTPS address, so use a tunnel for local testing and append the same secret path plus /mcp.

Configuration

Variable	Default	Description
ELEVENLABS_API_KEY	—	Required ElevenLabs API key.
MCP_PATH_SECRET	—	Required 24–128 character URL-safe secret.
ELEVENLABS_VOICE_ID	—	Required ElevenLabs voice ID used when a tool call omits voice_id; users can override it through the saved preference.
ELEVENLABS_MODEL_ID	eleven_v3	Default TTS model. Eleven v3 gives the model the most expressive delivery controls.
MAX_TEXT_LENGTH	5000	Maximum characters accepted per generation.
AUDIO_TTL_SECONDS	900	How long generated audio remains available.
MAX_CACHED_AUDIO_BYTES	52428800	Maximum total in-memory audio cache.
MAX_GENERATIONS_PER_MINUTE	10	Per-instance burst limit protecting ElevenLabs credits.
MAX_CONCURRENT_GENERATIONS	2	Maximum simultaneous TTS requests.
DATA_DIR	Railway volume or local data/	Optional preference storage override. Railway volumes are detected automatically through RAILWAY_VOLUME_MOUNT_PATH.
PUBLIC_BASE_URL	auto-detected	Optional canonical public origin.
PORT	3000	HTTP port; Railway supplies this automatically.

Privacy and storage

Text submitted to generate_speech is sent directly to ElevenLabs using the deployer's API key. Generated audio is held only in the running process memory and is removed after its expiry window or when the service restarts. The preferred voice record contains only its ElevenLabs ID, display name, and update time. This project does not include telemetry or a database.

Review ElevenLabs' own data handling and API terms before making a deployment available to other people.

Development checks

npm run check
npm test

The smoke test uses a local mock of the ElevenLabs API. It does not consume credits.

Relevant documentation

• OpenAI Apps SDK quickstart
• Build an MCP server
• Build a ChatGPT UI
• OpenAI decoupled data/render pattern
• ElevenLabs create speech API
• ElevenLabs text-to-speech best practices
• Prompting Eleven v3
• ElevenLabs list voices API
• Railway templates

License

MIT — see LICENSE.

---

Español

Esta plantilla crea una instancia privada del conector para cada persona. Railway solicita su propia clave de ElevenLabs y el ID de la voz que quiere usar, genera un camino MCP secreto y entrega el audio mediante un reproductor integrado en ChatGPT. Primero crea el MP3 y después abre el reproductor con una segunda herramienta rápida que no vuelve a gastar créditos. El reproductor usa un puente MCP Apps muy pequeño y sin dependencias, pero su visualización sigue dependiendo del cliente de ChatGPT y no se garantiza en todos los dispositivos; el enlace MP3 firmado permanece como alternativa. La voz es obligatoria durante el despliegue, aunque después el modelo puede mostrar otras voces y guardar una elección distinta mediante save_preferred_voice. No hay una cuenta central ni una base de datos compartida.