ElevenLabs

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

Claude Desktop 빠른 시작

1. ElevenLabs에서 API 키를 받으세요. 매월 1만 크레딧이 제공되는 무료 티어가 있습니다.
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)
• 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 인스펙터를 사용할 때 도구가 의도한 작업을 완료했음에도 불구하고 시간 초과 오류가 발생할 수 있습니다.

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

MCP ElevenLabs: spawn uvx ENOENT

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

which uvx

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