Voice MCP Server

MCP stdio server that lets Codex speak on demand. Codex starts the local stdio process, calls voice_speak, the server generates the audio, plays it through the system output, returns the tool result, and then waits for the next MCP request from the client.

Quick Start

npm install
npm run build

By default the server uses a local mock provider when ELEVENLABS_API_KEY is not set. To use ElevenLabs:

export ELEVENLABS_API_KEY="..."
npm run build

To use OpenAI Realtime streaming audio:

export VOICE_PROVIDER="openai-realtime"
export OPENAI_API_KEY="..."
npm run build

The Realtime provider is text-in/audio-out. It does not listen to the microphone. voice_speak sends the requested text as a Realtime conversation item, receives response.output_audio.delta chunks, and streams 24 kHz mono PCM audio to the local player as it arrives.

The transport is MCP over stdio; Codex starts dist/index.js directly. You do not run this as a daemon or keep a separate terminal open.

Example MCP client configuration:

{
  "mcpServers": {
    "voice": {
      "command": "node",
      "args": ["./dist/index.js"],
      "cwd": "/Users/francescperez/Documents/voice mcp server",
      "env": {
        "ELEVENLABS_API_KEY": "...",
        "ELEVENLABS_VOICE_ID": "hpp4J3VqNfWAUOO0d1Us",
        "ELEVENLABS_MODEL_ID": "eleven_flash_v2_5",
        "ELEVENLABS_FORMAT": "mp3"
      }
    }
  }
}

Example OpenAI Realtime MCP client configuration:

{
  "mcpServers": {
    "voice": {
      "command": "node",
      "args": ["./dist/index.js"],
      "cwd": "/Users/francescperez/Documents/voice mcp server",
      "env": {
        "VOICE_PROVIDER": "openai-realtime",
        "OPENAI_API_KEY": "...",
        "OPENAI_REALTIME_MODEL": "gpt-realtime-2.1",
        "OPENAI_REALTIME_VOICE": "marin",
        "OPENAI_REALTIME_FORMAT": "pcm16"
      }
    }
  }
}

The same block is available in .mcp.example.json. Keep real secrets in your local .env or .mcp.json; both are ignored by git.

Related MCP server: Kokoro TTS MCP Server

Tools

• voice_speak: generate and play speech.

• voice_wait: wait for a playback id to finish.

• voice_stop: stop current playback and clear pending items.

• voice_status: return queue/current/history state.

• voice_is_speaking: return whether audio is currently playing or being prepared.

• voice_set_profile: set the active voice profile.

• voice_list_profiles: list configured voice profiles.

voice_speak accepts:

{
  "text": "Hello",
  "waitUntilFinished": true,
  "voiceId": "optional voice id",
  "speed": 1.0,
  "volume": 1.0,
  "policy": "enqueue"
}

Queue policies are enqueue, interrupt, replace, and discard.

Resources

• voice://history: transcript/playback history as JSON.

• voice://status: current playback status as JSON.

Notifications

The server emits custom JSON-RPC notifications:

• voice.started

• voice.progress

• voice.finished

• voice.stopped

• voice.error

Configuration

Configuration can come from environment variables or from a file pointed at by VOICE_MCP_CONFIG or --config. JSON is supported, plus a flat key = value or key: value file for the keys shown in the design spec.

Example:

provider = "elevenlabs"
api_key = "${ELEVENLABS_API_KEY}"
voice_id = "hpp4J3VqNfWAUOO0d1Us"
model_id = "eleven_flash_v2_5"
format = "mp3"
volume = 1.0
speed = 1.0
output_device = "default"
cache = true

Only ELEVENLABS_API_KEY is needed for normal ElevenLabs use. Everything else has a default:

• VOICE_PROVIDER: auto-selects elevenlabs when ELEVENLABS_API_KEY exists; otherwise uses mock. Set openai-realtime to stream Realtime audio.

• ELEVENLABS_VOICE_ID: defaults to hpp4J3VqNfWAUOO0d1Us.

• ELEVENLABS_MODEL_ID: defaults to eleven_flash_v2_5.

• ELEVENLABS_MODEL: legacy alias for ELEVENLABS_MODEL_ID.

• ELEVENLABS_FORMAT: defaults to mp3; mp3 maps to ElevenLabs mp3_44100_128.

• OPENAI_API_KEY: required when VOICE_PROVIDER=openai-realtime.

• OPENAI_REALTIME_VOICE: defaults to marin.

• OPENAI_REALTIME_MODEL: defaults to gpt-realtime-2.1.

• OPENAI_REALTIME_FORMAT: defaults to pcm16, which maps to 24 kHz mono PCM.

• OPENAI_REALTIME_INSTRUCTIONS: optional narrator instructions for the Realtime model.

• VOICE_VOLUME: defaults to 1.0.

• VOICE_SPEED: defaults to 1.0.

• VOICE_OUTPUT_DEVICE: defaults to default.

• AUDIO_PLAYER_CMD: optional player command override.

• AUDIO_STREAM_PLAYER_CMD: optional streaming player command override. Placeholders: {sampleRate}, {channels}, {encoding}, and {volume}.

• VOICE_MCP_CONFIG: optional external config file.

• VOICE_CACHE: defaults to true.

• VOICE_CACHE_DIR: defaults to .voice-cache.

Audio Playback

On macOS the server uses afplay. On Linux it uses aplay for WAV and ffplay for other formats. You can override the command with AUDIO_PLAYER_CMD.

The mock provider emits WAV audio. ElevenLabs emits MP3 by default. OpenAI Realtime streaming uses ffplay by default:

ffplay -nodisp -autoexit -loglevel quiet -f s16le -sample_rate 24000 -ch_layout mono -volume 100 -i pipe:0