ElevenLabs

[!WARNING] 이 로컬 MCP 서버는 ElevenLabs 호스팅 MCP 서버를 위해 더 이상 사용되지 않습니다.

호스팅 서버는 https://api.elevenlabs.io/v1/mcp에서 사용할 수 있으며, 로컬에 설치하거나 실행할 것이 없습니다. OAuth로 인증하므로 API 키가 클라이언트에 복사되지 않습니다. 호스팅 MCP 서버 문서를 참조하여 Claude, Cursor 또는 다른 MCP 클라이언트에서 연결하세요.

이 저장소는 더 이상 적극적으로 유지 관리되지 않습니다.

공식 ElevenLabs Model Context Protocol (MCP) 서버로, 강력한 텍스트 음성 변환 및 오디오 처리 API와의 상호 작용을 가능하게 합니다. 이 서버를 통해 Claude Desktop, Cursor, Windsurf, OpenAI Agents 등의 MCP 클라이언트가 음성 생성, 음성 복제, 오디오 전사 등을 수행할 수 있습니다.

Claude Desktop 빠른 시작

1. ElevenLabs에서 API 키를 받으세요. 월 10,000크레딧의 무료 티어가 있습니다.
2. uv (Python 패키지 관리자)를 설치하고, curl -LsSf https://astral.sh/uv/install.sh | sh로 설치하거나 추가 설치 방법은 uv 저장소를 참조하세요.
3. Claude > 설정 > 개발자 > 구성 편집 > claude_desktop_config.json으로 이동하여 다음을 포함하세요:

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

Windows를 사용하는 경우, MCP 서버를 사용하려면 Claude Desktop에서 "개발자 모드"를 활성화해야 합니다. 왼쪽 상단의 햄버거 메뉴에서 "도움말"을 클릭하고 "개발자 모드 활성화"를 선택하세요.

기타 MCP 클라이언트

Cursor 및 Windsurf와 같은 다른 클라이언트의 경우:

1. pip install elevenlabs-mcp 실행
2. python -m elevenlabs_mcp --api-key={{PUT_YOUR_API_KEY_HERE}} --print를 실행하여 구성을 가져옵니다. MCP 클라이언트가 지정한 적절한 구성 디렉토리에 붙여넣으세요.

그게 전부입니다. 이제 MCP 클라이언트가 다음 도구를 통해 ElevenLabs와 상호 작용할 수 있습니다:

사용 예시

⚠️ 경고: 이러한 도구를 사용하려면 ElevenLabs 크레딧이 필요합니다.

Claude에게 다음과 같이 요청해 보세요:

• "필름 누아르 형사처럼 말하고 고전 영화에 대한 질문에 답할 수 있는 AI 에이전트를 만들어 줘"
• "현명하고 고대의 드래곤 캐릭터를 위한 세 가지 음성 변형을 생성한 다음, 내 음성 라이브러리에 추가할 가장 마음에 드는 음성을 선택하겠어"
• "내 목소리 녹음을 중세 기사처럼 들리게 변환해 줘"
• "동물들이 날씨에 반응하는 울창한 정글의 뇌우 사운드스케이프를 만들어 줘"
• "이 음성을 텍스트로 변환하고, 다른 화자를 식별한 다음, 각 사람에게 고유한 음성을 사용하여 다시 변환해 줘"

선택적 기능

파일 출력 구성

claude_desktop_config.json에서 다음 환경 변수를 사용하여 MCP 서버가 파일 출력을 처리하는 방식을 구성할 수 있습니다:

• ELEVENLABS_MCP_BASE_PATH: 파일 작업의 기본 경로를 지정합니다 (기본값: ~/Desktop). 이 디렉토리는 입력 파일의 보안 경계이기도 합니다: 로컬 파일을 읽는 도구(예: speech_to_text, isolate_audio, speech_to_speech, video_to_music, upload_music_for_inpainting)에 전달되는 모든 경로는 절대 경로든 상대 경로든 이 디렉토리 내부로 해석되어야 합니다. 외부의 경로(절대 경로이고 이전에 허용된 경우에도)는 거부됩니다. 읽거나 써야 하는 모든 것이 포함된 디렉토리로 설정하세요.
• ELEVENLABS_MCP_OUTPUT_MODE: 생성된 파일이 반환되는 방식을 제어합니다 (기본값: files)

출력 모드

ELEVENLABS_MCP_OUTPUT_MODE 환경 변수는 세 가지 모드를 지원합니다:

1. files (기본값): 파일을 디스크에 저장하고 파일 경로를 반환합니다

   "env": {
     "ELEVENLABS_API_KEY": "your-api-key",
     "ELEVENLABS_MCP_OUTPUT_MODE": "files"
   }
   

2. resources: 파일을 MCP 리소스로 반환합니다; 바이너리 데이터는 base64로 인코딩되고, 텍스트는 UTF-8 텍스트로 반환됩니다

   "env": {
     "ELEVENLABS_API_KEY": "your-api-key",
     "ELEVENLABS_MCP_OUTPUT_MODE": "resources"
   }
   

3. both: 파일을 디스크에 저장하고 MCP 리소스로도 반환합니다

   "env": {
     "ELEVENLABS_API_KEY": "your-api-key",
     "ELEVENLABS_MCP_OUTPUT_MODE": "both"
   }
   

리소스 모드의 이점:

• 파일이 base64로 인코딩된 데이터로 MCP 응답에 직접 반환됩니다
• 디스크 I/O가 필요 없음 - 컨테이너화되거나 서버리스 환경에 유용합니다
• MCP 클라이언트는 파일 시스템 액세스 없이 파일 콘텐츠에 즉시 액세스할 수 있습니다
• both 모드에서는 elevenlabs://filename URI 패턴을 사용하여 나중에 리소스를 가져올 수 있습니다

사용 사례:

• files: 기존 파일 기반 워크플로우, 로컬 개발
• resources: 클라우드 환경, 파일 시스템 액세스가 없는 MCP 클라이언트
• both: 최대 유연성, 캐싱 및 리소스 공유 시나리오

데이터 상주 키

ELEVENLABS_API_RESIDENCY 환경 변수로 데이터 상주 지역을 지정할 수 있습니다. 기본값은 "us"입니다.

참고: 데이터 상주는 엔터프라이즈 전용 기능입니다. 자세한 내용은 문서를 참조하세요.

기여

기여하거나 소스에서 실행하려면:

1. 저장소를 클론하세요:

git clone https://github.com/elevenlabs/elevenlabs-mcp
cd elevenlabs-mcp

2. uv를 사용하여 가상 환경을 만들고 종속성을 설치하세요:

uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

3. .env.example을 .env로 복사하고 ElevenLabs API 키를 추가하세요:

cp .env.example .env
# Edit .env and add your API key

4. 모든 것이 작동하는지 테스트를 실행하세요:

./scripts/test.sh
# Or with options
./scripts/test.sh --verbose --fail-fast

5. Claude Desktop에 서버를 설치하세요: mcp install elevenlabs_mcp/server.py

6. MCP Inspector로 로컬에서 디버그 및 테스트: mcp dev elevenlabs_mcp/server.py

문제 해결

Claude Desktop으로 실행할 때 로그는 다음 위치에서 찾을 수 있습니다:

• Windows: %APPDATA%\Claude\logs\mcp-server-elevenlabs.log
• macOS: ~/Library/Logs/Claude/mcp-server-elevenlabs.log

특정 도구 사용 시 시간 초과

음성 디자인 및 오디오 분리와 같은 일부 ElevenLabs API 작업은 해결하는 데 오랜 시간이 걸릴 수 있습니다. 개발 모드에서 MCP inspector를 사용할 때 도구가 의도한 작업을 완료했음에도 시간 초과 오류가 발생할 수 있습니다.

Claude와 같은 클라이언트를 사용할 때는 발생하지 않아야 합니다.

MCP ElevenLabs: spawn uvx ENOENT

"MCP ElevenLabs: spawn uvx ENOENT" 오류가 발생하면 터미널에서 다음 명령을 실행하여 절대 경로를 확인하세요:

which uvx

절대 경로(예: /usr/local/bin/uvx)를 얻은 후 해당 경로를 사용하도록 구성을 업데이트하세요(예: "command": "/usr/local/bin/uvx"). 이렇게 하면 올바른 실행 파일이 참조됩니다.