elevenlabs-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에서 "개발자 모드"를 활성화해야 합니다. 왼쪽 상단 햄버거 메뉴에서 "도움말"을 클릭하고 "개발자 모드 활성화"를 선택하세요.

Related MCP server: ElevenLabs MCP Server

기타 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"
   }

리소스 모드의 장점:

• 파일이 MCP 응답 내에 base64 인코딩 데이터로 직접 반환됩니다

• 디스크 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"). 이렇게 하면 올바른 실행 파일이 참조됩니다.