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

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"
      }
    }
  }
}

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

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.
• 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.
• 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.
• 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.