npm package: @mnicole-dev/elevenlabs-mcp-server
Description: MCP server for the ElevenLabs AI voice API — text-to-speech, sound generation, voice management, and more
Latest version: 1.0.0

# @mnicole-dev/elevenlabs-mcp-server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for the [ElevenLabs](https://elevenlabs.io) AI voice API. Generate realistic speech, create sound effects, isolate voices, and manage your voice library — all from any MCP-compatible client.

## Features

**12 tools** covering the core ElevenLabs API:

### Audio Generation (2 tools)

| Tool | Description |
|------|-------------|
| `text-to-speech` | Convert text to speech using any voice; saves MP3/PCM to a temp file and returns the path |
| `sound-generation` | Generate a sound effect from a text description; saves audio to a temp file |

### Voice Processing (1 tool)

| Tool | Description |
|------|-------------|
| `audio-isolation` | Remove background noise/music from an audio file, leaving only the voice |

### Voice Management (3 tools)

| Tool | Description |
|------|-------------|
| `list-voices` | List all available voices (premade + cloned) with IDs, categories, and labels |
| `get-voice` | Get full details for a voice including settings, samples, and supported models |
| `delete-voice` | Delete a custom or cloned voice from your account |

### Models (1 tool)

| Tool | Description |
|------|-------------|
| `list-models` | List all AI models with capabilities, supported languages, and cost factors |

### Account (2 tools)

| Tool | Description |
|------|-------------|
| `get-user` | Get user profile, subscription tier, and character usage/limits |
| `get-user-subscription` | Get detailed subscription fields including billing and feature flags |

### History (3 tools)

| Tool | Description |
|------|-------------|
| `list-history` | List TTS generation history with pagination and voice filter |
| `get-history-item` | Get details for a specific history item including text, settings, and feedback |
| `delete-history-item` | Delete a history item |

## Requirements

- Node.js 18+
- An [ElevenLabs account](https://elevenlabs.io) with an API key

## Installation

```bash
npm install -g @mnicole-dev/elevenlabs-mcp-server
```

Or run directly with `npx`:

```bash
npx @mnicole-dev/elevenlabs-mcp-server
```

## Configuration

Set your API key:

```bash
export ELEVENLABS_API_KEY=your-api-key-here
```

Get your API key from the [ElevenLabs API Keys page](https://elevenlabs.io/app/settings/api-keys).

### Claude Code

Add to your `~/.claude.json`:

```json
{
  "mcpServers": {
    "elevenlabs": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@mnicole-dev/elevenlabs-mcp-server"],
      "env": {
        "ELEVENLABS_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Claude Desktop

Add to your config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "elevenlabs": {
      "command": "npx",
      "args": ["-y", "@mnicole-dev/elevenlabs-mcp-server"],
      "env": {
        "ELEVENLABS_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Cursor / Windsurf / other MCP clients

Use the stdio transport with `npx -y @mnicole-dev/elevenlabs-mcp-server` as the command and set `ELEVENLABS_API_KEY` in the environment.

## Examples

### Generate speech

```
> Read this text aloud using voice ID "21m00Tcm4TlvDq8ikWAM": "Welcome to the future of voice AI."
```

Calls `text-to-speech` and returns the path to the generated audio file (e.g. `/tmp/elevenlabs-tts-1234567890.mp3`).

### Customize voice settings

```
> Generate speech for "Hello, world" with stability 0.8, similarity boost 0.9, and speaker boost enabled
```

Calls `text-to-speech` with:
```json
{
  "voiceId": "21m00Tcm4TlvDq8ikWAM",
  "text": "Hello, world",
  "stability": 0.8,
  "similarityBoost": 0.9,
  "speakerBoost": true
}
```

### Create a sound effect

```
> Generate a 5-second thunderstorm sound effect with heavy rain
```

Calls `sound-generation` with:
```json
{
  "text": "thunderstorm with heavy rain",
  "durationSeconds": 5,
  "promptInfluence": 0.4
}
```

### List voices and find an ID

```
> Show me all my available voices
```

Calls `list-voices` — returns voice IDs, names, categories (premade/cloned), labels (accent, gender, age, use case), and preview URLs.

### Isolate voice from a podcast

```
> Remove the background music from this audio: https://example.com/podcast-clip.mp3
```

Calls `audio-isolation` — downloads the file, sends it to ElevenLabs, and returns the path to the cleaned audio.

### Check remaining characters

```
> How many characters do I have left this month?
```

Calls `get-user` — shows character count, limit, percentage used, and reset date.

## Audio Output

For all tools that generate audio (`text-to-speech`, `sound-generation`, `audio-isolation`), the server:

1. Calls the ElevenLabs API
2. Writes the binary audio response to a temp file at `/tmp/elevenlabs-{type}-{timestamp}.mp3`
3. Returns the file path along with metadata (format, size, character count used, etc.)

The file can then be opened, played, or processed by the MCP client or downstream tools.

**Supported output formats for TTS:**

| Format | Description |
|--------|-------------|
| `mp3_44100_128` | MP3, 44.1kHz, 128kbps (default) |
| `mp3_44100_192` | MP3, 44.1kHz, 192kbps (higher quality) |
| `mp3_44100_64` | MP3, 44.1kHz, 64kbps (smaller files) |
| `mp3_22050_32` | MP3, 22.05kHz, 32kbps (smallest) |
| `pcm_44100` | PCM, 44.1kHz, 16-bit (uncompressed) |
| `pcm_24000` | PCM, 24kHz, 16-bit |
| `pcm_22050` | PCM, 22.05kHz, 16-bit |
| `pcm_16000` | PCM, 16kHz, 16-bit |
| `ulaw_8000` | μ-law, 8kHz (telephony) |

## How it works

1. The MCP client sends a tool call to the server via stdio
2. The server reads `ELEVENLABS_API_KEY` from the environment
3. The request is forwarded to `https://api.elevenlabs.io` with the `xi-api-key` header
4. JSON responses are formatted as readable text; binary audio is saved to `/tmp/` and the path is returned

## Development

```bash
git clone https://github.com/mnicole-dev/elevenlabs-mcp-server.git
cd elevenlabs-mcp-server
pnpm install
pnpm dev          # Run with tsx (requires ELEVENLABS_API_KEY)
pnpm build        # Build to dist/
```

## License

MIT