Skip to content
Back to search

elevenlabs-mcp

The official ElevenLabs MCP server

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/elevenlabs--elevenlabs-mcp/badge.svg)](/listings/elevenlabs--elevenlabs-mcp)

HTML

<a href="/listings/elevenlabs--elevenlabs-mcp"><img src="/api/listings/elevenlabs--elevenlabs-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

1. Get your API key from [ElevenLabs](https://elevenlabs.io/app/settings/api-keys). There is a free tier with 10k credits per month. 2. Install `uv` (Python package manager), install with `curl -LsSf https://astral.sh/uv/install.sh | sh` or see the `uv` [repo](https://github.com/astral-sh/uv) for additional install methods. 3. Go to Claude > Settings > Developer > Edit Config > claude_desktop_config.json to include the following:

{
  "mcpServers": {
    "ElevenLabs": {
      "command": "uvx",
      "args": ["elevenlabs-mcp"],
      "env": {
        "ELEVENLABS_API_KEY": "<insert-your-api-key-here>"
      }
    }
  }
}

If you're using Windows, you will have to enable "Developer Mode" in Claude Desktop to use the MCP server. Click "Help" in the hamburger menu at the top left and select "Enable Developer Mode".

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 187 lines · 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ![export](https://github.com/user-attachments/assets/ee379feb-348d-48e7-899c-134f7f7cd74f)
  2. > [!WARNING]
  3. > **This local MCP server is deprecated in favor of the [ElevenLabs hosted MCP server](https://elevenlabs.io/docs/agents-platform/operate/hosted-mcp).**
  4. >
  5. > The hosted server is available at `https://api.elevenlabs.io/v1/mcp`, with nothing to install or run locally. It authenticates with OAuth, so no API keys are copied into your client. See the [hosted MCP server documentation](https://elevenlabs.io/docs/agents-platform/operate/hosted-mcp) to connect from Claude, Cursor, or any other MCP client.
  6. >
  7. > This repository is no longer actively maintained.
  8. <div class="title-block" style="text-align: center;" align="center">
  9. [![Discord Community](https://img.shields.io/badge/discord-@elevenlabs-000000.svg?style=for-the-badge&logo=discord&labelColor=000)](https://discord.gg/elevenlabs)
  10. [![Twitter](https://img.shields.io/badge/Twitter-@elevenlabsio-000000.svg?style=for-the-badge&logo=twitter&labelColor=000)](https://x.com/ElevenLabsDevs)
  11. [![PyPI](https://img.shields.io/badge/PyPI-elevenlabs--mcp-000000.svg?style=for-the-badge&logo=pypi&labelColor=000)](https://pypi.org/project/elevenlabs-mcp)
  12. [![Tests](https://img.shields.io/badge/tests-passing-000000.svg?style=for-the-badge&logo=github&labelColor=000)](https://github.com/elevenlabs/elevenlabs-mcp-server/actions/workflows/test.yml)
  13. </div>
  14. <p align="center">
  15. Official ElevenLabs <a href="https://github.com/modelcontextprotocol">Model Context Protocol (MCP)</a> server that enables interaction with powerful Text to Speech and audio processing APIs. This server allows MCP clients like <a href="https://www.anthropic.com/claude">Claude Desktop</a>, <a href="https://www.cursor.so">Cursor</a>, <a href="https://codeium.com/windsurf">Windsurf</a>, <a href="https://github.com/openai/openai-agents-python">OpenAI Agents</a> and others to generate speech, clone voices, transcribe audio, and more.
  16. </p>
  17. <!--
  18. mcp-name: io.github.elevenlabs/elevenlabs-mcp
  19. -->
  20. ## Quickstart with Claude Desktop
  21. 1. Get your API key from [ElevenLabs](https://elevenlabs.io/app/settings/api-keys). There is a free tier with 10k credits per month.
  22. 2. Install `uv` (Python package manager), install with `curl -LsSf https://astral.sh/uv/install.sh | sh` or see the `uv` [repo](https://github.com/astral-sh/uv) for additional install methods.
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 31 on GitHub
  23. 3. Go to Claude > Settings > Developer > Edit Config > claude_desktop_config.json to include the following:
  24. ```
  25. {
  26. "mcpServers": {
  27. "ElevenLabs": {
  28. "command": "uvx",
  29. "args": ["elevenlabs-mcp"],
  30. "env": {
  31. "ELEVENLABS_API_KEY": "<insert-your-api-key-here>"
  32. }
  33. }
  34. }
  35. }
  36. ```
  37. If you're using Windows, you will have to enable "Developer Mode" in Claude Desktop to use the MCP server. Click "Help" in the hamburger menu at the top left and select "Enable Developer Mode".
  38. ## Other MCP clients
  39. For other clients like Cursor and Windsurf, run:
  40. 1. `pip install elevenlabs-mcp`
  41. 2. `python -m elevenlabs_mcp --api-key={{PUT_YOUR_API_KEY_HERE}} --print` to get the configuration. Paste it into appropriate configuration directory specified by your MCP client.
  42. That's it. Your MCP client can now interact with ElevenLabs through these tools:
  43. ## Example usage
  44. ⚠️ Warning: ElevenLabs credits are needed to use these tools.
  45. Try asking Claude:
  46. - "Create an AI agent that speaks like a film noir detective and can answer questions about classic movies"
  47. - "Generate three voice variations for a wise, ancient dragon character, then I will choose my favorite voice to add to my voice library"
  48. - "Convert this recording of my voice to sound like a medieval knight"
  49. - "Create a soundscape of a thunderstorm in a dense jungle with animals reacting to the weather"
  50. - "Turn this speech into text, identify different speakers, then convert it back using unique voices for each person"
  51. ## Optional features
  52. ### File Output Configuration
  53. You can configure how the MCP server handles file outputs using these environment variables in your `claude_desktop_config.json`:
  54. - **`ELEVENLABS_MCP_BASE_PATH`**: Specify the base path for file operations (default: `~/Desktop`). This directory is also the security boundary for **input** files: any path passed to a tool that reads a local file (e.g. `speech_to_text`, `isolate_audio`, `speech_to_speech`, `video_to_music`, `upload_music_for_inpainting`) must resolve inside this directory, whether given as an absolute or relative path. Paths outside it — even if absolute and previously accepted — are rejected. Set this to a directory that contains everything you need to read from or write to.
  55. - **`ELEVENLABS_MCP_OUTPUT_MODE`**: Control how generated files are returned (default: `files`)
  56. #### Output Modes
  57. The `ELEVENLABS_MCP_OUTPUT_MODE` environment variable supports three modes:
  58. 1. **`files`** (default): Save files to disk and return file paths
  59. ```json
  60. "env": {
  61. "ELEVENLABS_API_KEY": "your-api-key",
  62. "ELEVENLABS_MCP_OUTPUT_MODE": "files"
  63. }
  64. ```
  65. 2. **`resources`**: Return files as MCP resources; binary data is base64-encoded, text is returned as UTF-8 text
  66. ```json
  67. "env": {
  68. "ELEVENLABS_API_KEY": "your-api-key",
  69. "ELEVENLABS_MCP_OUTPUT_MODE": "resources"
  70. }
  71. ```
  72. 3. **`both`**: Save files to disk AND return as MCP resources
  73. ```json
  74. "env": {
  75. "ELEVENLABS_API_KEY": "your-api-key",
  76. "ELEVENLABS_MCP_OUTPUT_MODE": "both"
  77. }
  78. ```
  79. **Resource Mode Benefits:**
  80. - Files are returned directly in the MCP response as base64-encoded data
  81. - No disk I/O required - useful for containerized or serverless environments
  82. - MCP clients can access file content immediately without file system access
  83. - In `both` mode, resources can be fetched later using the `elevenlabs://filename` URI pattern
  84. **Use Cases:**
  85. - `files`: Traditional file-based workflows, local development
  86. - `resources`: Cloud environments, MCP clients without file system access
  87. - `both`: Maximum flexibility, caching, and resource sharing scenarios
  88. ### Data residency keys
  89. You can specify the data residency region with the `ELEVENLABS_API_RESIDENCY` environment variable. Defaults to `"us"`.
  90. **Note:** Data residency is an enterprise only feature. See [the docs](https://elevenlabs.io/docs/product-guides/administration/data-residency#overview) for more details.
  91. ## Contributing
  92. If you want to contribute or run from source:
  93. 1. Clone the repository:
  94. ```bash
  95. git clone https://github.com/elevenlabs/elevenlabs-mcp
  96. cd elevenlabs-mcp
  97. ```
  98. 2. Create a virtual environment and install dependencies [using uv](https://github.com/astral-sh/uv):
  99. ```bash
  100. uv venv
  101. source .venv/bin/activate
  102. uv pip install -e ".[dev]"
  103. ```
  104. 3. Copy `.env.example` to `.env` and add your ElevenLabs API key:
  105. ```bash
  106. cp .env.example .env
  107. # Edit .env and add your API key
  108. ```
  109. 4. Run the tests to make sure everything is working:
  110. ```bash
  111. ./scripts/test.sh
  112. # Or with options
  113. ./scripts/test.sh --verbose --fail-fast
  114. ```
  115. 5. Install the server in Claude Desktop: `mcp install elevenlabs_mcp/server.py`
  116. 6. Debug and test locally with MCP Inspector: `mcp dev elevenlabs_mcp/server.py`
  117. ## Troubleshooting
  118. Logs when running with Claude Desktop can be found at:
  119. - **Windows**: `%APPDATA%\Claude\logs\mcp-server-elevenlabs.log`
  120. - **macOS**: `~/Library/Logs/Claude/mcp-server-elevenlabs.log`
  121. ### Timeouts when using certain tools
  122. Certain ElevenLabs API operations, like voice design and audio isolation, can take a long time to resolve. When using the MCP inspector in dev mode, you might get timeout errors despite the tool completing its intended task.
  123. This shouldn't occur when using a client like Claude.
  124. ### MCP ElevenLabs: spawn uvx ENOENT
  125. If you encounter the error "MCP ElevenLabs: spawn uvx ENOENT", confirm its absolute path by running this command in your terminal:
  126. ```bash
  127. which uvx
  128. ```
  129. Once you obtain the absolute path (e.g., `/usr/local/bin/uvx`), update your configuration to use that path (e.g., `"command": "/usr/local/bin/uvx"`). This ensures that the correct executable is referenced.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.