ElevenLabs MCP Server

Streamable HTTP MCP server for ElevenLabs — text-to-speech, speech-to-text, and voice management.

Author: overment

[!WARNING] You connect this server to your MCP client at your own responsibility. Language models can make mistakes, misinterpret instructions, or perform unintended actions. Review tool outputs and verify results before using generated audio or transcripts in production.

Features

• ✅ Text to Speech — Convert text to audio using any ElevenLabs voice
• ✅ Speech to Text — Transcribe audio/video files with Scribe models
• ✅ Voice Management — List and inspect available voices
• ✅ Transcript Management — Retrieve and delete transcripts
• ✅ Dual Runtime — Node.js/Bun or Cloudflare Workers
• ✅ Multiple Input Methods — File URLs or base64-encoded data

Design Principles

• LLM-friendly: Tools have clear descriptions and structured outputs
• Flexible input: Speech-to-text accepts both file URLs and base64 data
• Rich output: TTS returns base64 audio; STT returns text with metadata

---

Installation

Prerequisites: Bun, Node.js 20+, ElevenLabs account.

cd elevenlabs-mcp
bun install

Configuration

Create a .env file with your ElevenLabs API key from ElevenLabs Settings:

PORT=3000
AUTH_STRATEGY=api_key
API_KEY=xi_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
API_KEY_HEADER=xi-api-key
ELEVENLABS_API_KEY=xi_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Note: ELEVENLABS_API_KEY is used by the tools to authenticate with the ElevenLabs API. The API_KEY / API_KEY_HEADER pair is used to protect the MCP endpoint itself.

Start

bun dev
# MCP: http://127.0.0.1:3000/mcp

---

Client Configuration

MCP Inspector (quick test):

bunx @modelcontextprotocol/inspector
# Connect to: http://localhost:3000/mcp

Claude Desktop / Cursor:

{
  "mcpServers": {
    "elevenlabs": {
      "command": "bunx",
      "args": [
        "mcp-remote",
        "http://localhost:3000/mcp",
        "--header",
        "x-api-key: ${ELEVENLABS_API_KEY}"
      ]
    }
  }
}

---

Tools

list_voices

List all available ElevenLabs voices. Call this first to discover voice IDs.

// Input
{}

// Output
{
  count: number;
  voices: Array<{
    voice_id: string;
    name: string;
    category: string;
    labels: Record<string, string>;
    preview_url: string | null;
  }>;
}

text_to_speech

Convert text into speech audio. Returns base64-encoded audio data.

// Input
{
  text: string;                    // Required — text to convert
  voice_id: string;                // Required — from list_voices
  model_id?: string;               // Default: eleven_multilingual_v2
  output_format?: string;          // Default: mp3_44100_128
  language_code?: string;          // ISO 639-1 code
  voice_settings?: {
    stability?: number;            // 0-1
    similarity_boost?: number;     // 0-1
    speed?: number;                // 0.1-3.0
    style?: number;                // 0-1
  };
}

// Output: base64-encoded audio as a data URI resource

speech_to_text

Transcribe an audio or video file. Accepts either a URL or base64 data.

// Input
{
  file_url?: string;               // HTTPS URL of the file
  file_base64?: string;            // Base64-encoded file content
  file_name?: string;              // Filename when using base64
  model_id?: string;               // scribe_v1 (default) or scribe_v2
  language_code?: string;          // ISO 639-1/3 code (auto-detect if omitted)
  diarize?: boolean;               // Identify speakers
  num_speakers?: number;           // Expected speaker count (1-32)
  tag_audio_events?: boolean;      // Tag (laughter), (footsteps), etc.
  timestamps_granularity?: string; // none, word, character
}

// Output
{
  text: string;
  language_code: string;
  language_probability: number;
  transcription_id: string | null;
}

get_voice

Get detailed metadata about a specific voice.

// Input
{ voice_id: string }

// Output: voice details including name, category, labels, settings, preview_url

get_transcript

Retrieve a previously generated transcript by ID.

// Input
{ transcription_id: string }

// Output: full transcript text with language and word count

delete_transcript

Delete a previously generated transcript.

// Input
{ transcription_id: string }

// Output: deletion confirmation

---

Examples

1. Generate speech from text

// First, find a voice
{ "name": "list_voices", "arguments": {} }

// Then generate audio
{
  "name": "text_to_speech",
  "arguments": {
    "text": "Hello, this is a test of the ElevenLabs text to speech system.",
    "voice_id": "JBFqnCBsd6RMkjVDRZzb",
    "output_format": "mp3_44100_128"
  }
}

2. Transcribe an audio file from URL

{
  "name": "speech_to_text",
  "arguments": {
    "file_url": "https://example.com/recording.mp3",
    "diarize": true,
    "language_code": "en"
  }
}

3. Transcribe with speaker identification

{
  "name": "speech_to_text",
  "arguments": {
    "file_url": "https://example.com/meeting.mp3",
    "diarize": true,
    "num_speakers": 3,
    "tag_audio_events": true
  }
}

---

HTTP Endpoints

Endpoint	Method	Purpose
/mcp	POST	MCP JSON-RPC 2.0
/mcp	GET	SSE stream (Node.js only)
/health	GET	Health check

---

Development

bun dev           # Start with hot reload
bun run typecheck # TypeScript check
bun run lint      # Lint code
bun run build     # Production build
bun start         # Run production

---

Architecture

src/
├── shared/
│   └── tools/
│       └── elevenlabs/        # ElevenLabs tool definitions
│           ├── api.ts         # Shared API helpers
│           ├── text-to-speech.ts
│           ├── speech-to-text.ts
│           ├── list-voices.ts
│           ├── get-voice.ts
│           ├── get-transcript.ts
│           └── delete-transcript.ts
├── config/
│   ├── env.ts                 # Environment config
│   └── metadata.ts            # Tool & server metadata
├── core/
│   ├── capabilities.ts        # MCP capabilities
│   ├── context.ts             # Request context
│   └── mcp.ts                 # MCP server builder
├── http/
│   ├── app.ts                 # Hono HTTP app
│   ├── middlewares/            # Auth, CORS
│   └── routes/                # Health, MCP
├── index.ts                   # Node.js entry
└── worker.ts                  # Workers entry

---

Troubleshooting

Issue	Solution
"Missing ElevenLabs API key"	Set ELEVENLABS_API_KEY in .env or configure auth headers
"Rate limit exceeded"	ElevenLabs has per-plan rate limits. Wait and retry.
Empty audio response	Verify voice_id exists using list_voices
Transcription fails	Ensure file URL is accessible or base64 is valid
422 Validation Error	Check input parameters match the API spec

---

License

MIT