Login
elevenlabs/elevenlabs-mcpPlease refer to the latest official releases for information GitHub Homepage

ElevenLabs 공식 MCP 서버로, 텍스트 음성 변환, 음성 복제, 오디오 전사 등 AI 오디오 처리 기능을 지원합니다.

MITPython 0.8kelevenlabselevenlabs-mcp Last Updated: 2025-07-19

ElevenLabs MCP 서버 상세 소개

프로젝트 개요

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

핵심 기능

주요 특징

  • 텍스트 음성 변환(TTS): 텍스트를 자연스러운 음성으로 변환
  • 음성 복제: 특정 음성 특징을 복사 및 모방
  • 오디오 전사: 오디오 파일을 텍스트로 변환
  • 음성 디자인: 독특한 음성 구성 생성 및 맞춤 설정
  • 오디오 격리: 복잡한 오디오에서 특정 사운드 분리
  • 음향 효과 생성: 다양한 음향 효과 및 음향 풍경 생성

지원되는 클라이언트

  • Claude Desktop
  • Cursor
  • Windsurf
  • OpenAI Agents
  • 기타 MCP 프로토콜 호환 클라이언트

설치 구성

사전 요구 사항

  1. ElevenLabs에서 API 키 획득 (무료 버전은 매월 10k 크레딧 제공)
  2. uv (Python 패키지 관리자) 설치:
    curl -LsSf https://astral.sh/uv/install.sh | sh

Claude Desktop 구성

Claude > Settings > Developer > Edit Config > claude_desktop_config.json에 다음 구성 추가:

{
  "mcpServers": {
    "ElevenLabs": {
      "command": "uvx",
      "args": ["elevenlabs-mcp"],
      "env": {
        "ELEVENLABS_API_KEY": "<여기에-API-키-입력>"
      }
    }
  }
}

Windows 사용자 주의: Claude Desktop에서 "개발자 모드"를 활성화해야 합니다. 좌측 상단 햄버거 메뉴의 "Help"에서 "Enable Developer Mode"를 선택하십시오.

기타 클라이언트 구성

Cursor 및 Windsurf 등 클라이언트의 경우:

pip install elevenlabs-mcp
python -m elevenlabs_mcp --api-key={{여기에_API_키_입력}} --print

그런 다음 출력된 구성을 해당 MCP 클라이언트의 구성 디렉토리에 붙여넣습니다.

사용 예시

설치 후 다음 작업을 시도해 볼 수 있습니다.

  • "흑백 영화 형사처럼 말하는 AI 에이전트를 만들어 고전 영화에 대한 질문에 답변하도록 하세요."
  • "현명한 고룡 캐릭터를 위한 세 가지 음성 변형을 생성한 다음, 가장 좋아하는 음성을 선택하여 음성 라이브러리에 추가하겠습니다."
  • "이 녹음을 중세 기사처럼 들리도록 변환하세요."
  • "동물들이 날씨에 반응하는 밀림 속 뇌우의 음향 풍경을 만드세요."
  • "이 음성을 텍스트로 변환하고, 다른 화자를 식별한 다음, 각 사람에게 고유한 음성을 사용하여 다시 음성으로 변환하세요."

개발 및 기여

소스 코드에서 실행

  1. 저장소 복제:

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

  2. 가상 환경 생성 및 종속성 설치:

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

  3. 환경 변수 구성:

    cp .env.example .env
# .env 파일을 편집하고 API 키를 추가하십시오.

  4. 테스트 실행:

    ./scripts/test.sh
# 또는 옵션과 함께 실행
./scripts/test.sh --verbose --fail-fast

디버깅 및 테스트

  • Claude Desktop에 서버 설치:

    mcp install elevenlabs_mcp/server.py

  • 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 MCP 서버는 ElevenLabs API의 추상화 계층으로, 대규모 언어 모델에 전체 ElevenLabs AI 오디오 플랫폼에 대한 컨텍스트 액세스를 제공합니다. 개발자 친화적인 로컬 인터페이스 역할을 하며, 요청을 ElevenLabs의 클라우드 API로 전달합니다.

주의 사항

  1. 시간 초과 처리: 일부 ElevenLabs API 작업(예: 음성 디자인 및 오디오 격리)은 완료하는 데 시간이 오래 걸릴 수 있습니다. MCP inspector 개발 모드에서 시간 초과 오류가 발생할 수 있지만 작업은 여전히 완료됩니다. Claude 등 클라이언트를 사용할 때는 이 문제가 발생하지 않습니다.

  2. 경로 구성: ELEVENLABS_MCP_BASE_PATH 환경 변수를 추가하여 MCP 서버가 상대 경로 파일을 찾고 출력하는 기본 경로를 지정할 수 있습니다.

  3. 오류 해결: "MCP ElevenLabs: spawn uvx ENOENT" 오류가 발생하면 which uvx 명령을 사용하여 절대 경로를 확인한 다음 구성에서 전체 경로를 사용하십시오 (예: "command": "/usr/local/bin/uvx").

프로젝트 가치

이 프로젝트는 AI 애플리케이션 개발자에게 다음을 제공합니다.

  • 표준화된 오디오 처리 인터페이스
  • 원활한 음성 합성 통합
  • 강력한 오디오 분석 기능
  • 플랫폼 간 호환성
  • 엔터프라이즈급 오디오 품질

MCP 프로토콜을 통해 개발자는 ElevenLabs의 고품질 오디오 처리 기능을 다양한 AI 애플리케이션에 쉽게 통합하여 오디오 관련 기능 개발 프로세스를 크게 간소화할 수 있습니다.

Star History Chart