AI 음성 생성 MCP 서버 유사

Claude 와 Cursor를 통합하고 Model Context Protocol(MCP)을 사용하는 Resemble AI 음성 생성 API를 위한 서버 구현입니다.

특징

• Resemble AI의 음성을 사용하여 텍스트에서 음성 오디오를 생성합니다.

• 사용 가능한 음성 모델 나열

• 오디오를 로컬 파일 또는 base64로 인코딩된 문자열로 반환합니다.

• 다양한 연결 방법:

  • SSE 전송 - 네트워크 기반 서버 전송 이벤트(기본값)

  • StdIO Transport - 직접 프로세스 통신

Related MCP server: MCP Sound Tool

설치 지침

필수 조건

• Python 3.10 이상

• Resemble AI API 키( Resemble AI 에 가입하세요)

환경 설정

옵션 1: Conda 사용(권장)

지엑스피1

옵션 2: 가상 환경 사용

# Run the setup script
./scripts/setup_venv.sh

# Activate the environment
source venv/bin/activate

구성

Resemble AI API 키를 환경 변수로 설정하세요.

export RESEMBLE_API_KEY="your_api_key_here"

또는 프로젝트 루트에 다음 내용이 포함된 .env 파일을 만듭니다.

RESEMBLE_API_KEY=your_api_key_here

서버 실행

실행 스크립트 사용(권장)

원하는 구현을 선택하세요:

# Run the MCP SDK implementation with SSE transport (default)
./run_server.sh mcp 8083

# Run the HTTP implementation
./run_server.sh http 8083

# Run with StdIO transport (for direct process communication)
./run_server.sh stdio

CLI를 직접 사용하기

# Run the MCP SDK implementation with SSE transport
python -m src.cli --implementation mcp --port 8083

# Run with StdIO transport
python -m src.cli --implementation stdio

Claude Desktop에 연결

SSE 운송 연결

claude_desktop_config.json 파일을 만듭니다.

{
  "mcpServers": {
    "resemble-ai": {
      "sseUrl": "http://localhost:8083/sse"
    }
  }
}

StdIO 전송 연결

claude_desktop_config.json 파일을 만듭니다.

{
  "mcpServers": {
    "resemble-ai": {
      "command": "python",
      "args": ["-m", "src.cli", "--implementation", "stdio"],
      "env": {
        "RESEMBLE_API_KEY": "your_api_key_here"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

커서에 연결

SSE 운송 연결

1. 설정 → AI → MCP 서버로 이동하세요.

2. "서버 추가"를 클릭하세요

3. 연결 유형으로 "SSE"를 선택하세요

4. URL을 http://localhost:8083/sse 로 설정하세요.

StdIO 전송 연결

1. 설정 → AI → MCP 서버로 이동하세요.

2. "서버 추가"를 클릭하세요

3. 연결 유형으로 "하위 프로세스"를 선택하세요

4. 명령을 python -m src.cli --implementation stdio 로 설정합니다.

5. 선택적으로 환경 변수를 추가합니다.

   • RESEMBLE_API_KEY : Resemble AI API 키

사용 가능한 도구

list_voices

Resemble AI에서 사용 가능한 음성 모델을 나열합니다.

generate_tts

텍스트에서 음성 오디오를 생성합니다.

매개변수:

• text : 음성으로 변환할 텍스트

• voice_id : 사용할 음성의 ID

• return_type : 오디오 반환 방법: 'file' 또는 'base64' (선택 사항, 기본값: 'file')

• output_filename : 확장자 없는 출력 파일 이름(선택 사항)

구현 세부 사항

이 프로젝트에는 여러 가지 구현이 포함됩니다.

• src/resemble_mcp_server.py : SSE 전송을 사용하는 MCP SDK를 사용합니다.

• src/resemble_stdio_server.py : 직접 프로세스 통신을 위해 StdIO 전송을 사용합니다.

• src/resemble_http_server.py : SSE를 사용한 HTTP 구현(폴백)

• src/resemble_ai_server.py : 직접 API 구현

• src/resemble_ai_sdk_server.py : 공식 Resemble SDK를 사용한 구현

문제 해결

MCP SDK 가져오기 오류

MCP SDK를 가져오는 데 문제가 발생하면 서버는 자동으로 SSE 전송을 사용하는 HTTP 구현으로 돌아갑니다.

연결 문제

Claude 또는 Cursor가 서버에 연결할 수 없는 경우:

1. 서버가 실행 중인지 확인하세요

2. 올바른 URL이 구성되었는지 확인하세요

3. API 키가 유효한지 확인하세요

4. 서버 로그에서 오류를 찾아보세요

StdIO 대 SSE 전송

• 서버를 별도로 또는 다른 컴퓨터에서 실행하려는 경우 SSE Transport를 사용하세요.

• Claude/Cursor가 서버 프로세스를 관리하도록 하려면 StdIO Transport를 사용하세요.

예시

예제 사용 사례는 examples/ 디렉토리에서 확인할 수 있습니다.

📁 저장소 구조

.
├── src/                 # Source code for the server implementations
│   ├── resemble_mcp_server.py    # MCP SDK implementation (recommended)
│   ├── resemble_http_server.py   # HTTP API implementation
│   ├── resemble_ai_server.py     # Direct API implementation
│   ├── resemble_ai_sdk_server.py # Resemble SDK implementation
│   └── cli.py           # CLI tool for running the server
├── tests/               # Test scripts
├── docs/                # Documentation
├── examples/            # Example usage and tools
├── scripts/             # Setup and utility scripts
├── output/              # Generated audio output directory
├── .env.example         # Example environment configuration
├── requirements.txt     # Python dependencies
└── README.md            # This file

🚀 빠른 설정

설치를 쉽게 하기 위해 두 개의 설치 스크립트가 제공됩니다.

Conda 사용(권장)

# Make the script executable
chmod +x scripts/setup_environment.sh

# Run the setup script
./scripts/setup_environment.sh

Python venv 사용하기

# Make the script executable
chmod +x scripts/setup_venv.sh

# Run the setup script
./scripts/setup_venv.sh

두 스크립트 모두 다음을 수행합니다.

1. Python 3.10+ 환경 만들기

2. 필요한 모든 종속성을 설치하세요

3. 템플릿 .env 파일 설정

4. 오디오 파일의 출력 디렉토리를 만듭니다.

수동 설치

수동으로 설정하려면 다음을 수행하세요.

1. Python 3.10+ 환경을 만듭니다.

   # Using conda
   conda create -n resemble_mcp python=3.10
   conda activate resemble_mcp
   
   # OR using venv (with Python 3.10+ already installed)
   python3.10 -m venv venv
   source venv/bin/activate

2. 종속성 설치:

   pip install uvicorn fastapi python-dotenv requests pydantic httpx sse-starlette
   pip install git+https://github.com/modelcontextprotocol/python-sdk.git

3. 환경 변수를 설정하세요.

   cp .env.example .env

   .env 파일을 편집하고 Resemble AI API 키를 추가하세요.

   RESEMBLE_API_KEY=your_api_key_here

   선택 사항: 오디오 출력 설정 사용자 정의

   OUTPUT_DIR=./output
   AUDIO_FORMAT=mp3

4. 출력 디렉토리 생성:

   mkdir -p output

🚀 서버 실행

모든 구현을 지원하는 새로운 CLI 도구를 사용하여 서버를 실행할 수 있습니다.

# Activate your environment if not already activated
conda activate resemble_mcp
# OR
source venv/bin/activate

# Run the MCP SDK implementation (recommended)
python -m src.cli --implementation mcp --port 8083

# Other implementations:
# HTTP API implementation
python -m src.cli --implementation http --port 8083
# Direct API implementation
python -m src.cli --implementation direct --port 8083
# Resemble SDK implementation
python -m src.cli --implementation sdk --port 8083

🔌 커서 AI와 통합

커서는 SSE 인터페이스를 통해 Resemble AI 음성 생성 서버와 상호 작용할 수 있습니다.

1. 커서에서 설정 → AI → MCP 서버로 이동합니다.

2. "서버 추가"를 클릭하고 SSE URL을 입력하세요: http://localhost:8083/sse (필요한 경우 포트를 조정하세요)

3. 구성을 저장합니다

🔌 Claude Desktop과 통합

1. Claude Desktop 설정에서 MCP 서버를 구성하세요.

   {
     "mcpServers": {
       "resemble-ai": {
         "command": "python",
         "args": ["-m", "src.cli", "--implementation", "mcp"],
         "env": {
           "RESEMBLE_API_KEY": "your_api_key_here"
         },
         "disabled": false,
         "autoApprove": []
       }
     }
   }

🛠️ 도구 문서

목록_음성

Resemble AI에서 사용 가능한 모든 음성 모델을 나열합니다.

매개변수: 없음

보고:

• voices : ID, 이름, 성별, 언어, 악센트 및 설명이 포함된 사용 가능한 음성 모델 목록

생성_tts

텍스트에서 음성 오디오를 생성합니다.

매개변수:

• text (문자열, 필수): 음성으로 변환할 텍스트

• voice_id (문자열, 필수): 사용할 음성의 ID

• return_type (문자열, 선택 사항): 오디오 반환 방법: 'file' 또는 'base64'(기본값: 'file')

• output_filename (문자열, 선택 사항): 확장자가 없는 출력 파일 이름(기본값: 자동 생성 이름)

보고:

• success (부울): 작업이 성공했는지 여부

• message (문자열): 상태 메시지

• audio_data (문자열, 선택 사항): Base64로 인코딩된 오디오 데이터(return_type이 'base64'인 경우)

• file_path (문자열, 선택 사항): 저장된 오디오 파일의 경로(return_type이 'file'인 경우)

💬 예시 프롬프트

Cursor 또는 Claude Desktop에 연결되면 다음과 같은 프롬프트를 사용할 수 있습니다.

사용 가능한 음성 나열:

List all available voice models from Resemble AI.

음성 오디오 생성:

Generate audio of the text "Hello, this is a test of the Resemble AI voice generation system" using a male English voice.

⚠️ 문제 해결

• Python 버전 문제 : MCP 패키지에는 Python 3.10 이상이 필요합니다. 제공된 설치 스크립트를 사용하여 올바른 환경을 만드세요.

• API 연결 문제 : 올바른 API 엔드포인트를 사용하고 있는지 확인하세요. Resemble AI API 엔드포인트는 https://app.resemble.ai/api/v2/ 입니다.

• 인증 오류 : API 키가 올바르고 만료되지 않았는지 확인하세요.

• 누락된 프로젝트 : API를 사용하려면 Resemble 계정에 최소 하나 이상의 프로젝트가 있어야 합니다. 필요한 경우 Resemble AI 대시보드를 통해 프로젝트를 생성하세요.

• 커서 SSE 연결 오류 : 커서가 SSE를 통해 연결에 실패하는 경우 다음을 확인하세요.

  • 서버가 지정된 포트에서 실행 중입니다.

  • 올바른 /sse 엔드포인트를 사용하고 있습니다.

  • 방화벽이 연결을 차단하고 있지 않습니다.

  • 서버와 커서를 모두 다시 시작해 보세요.

📚 추가 문서

더 자세한 내용은 docs/ 디렉토리에 있는 파일을 참조하세요.

📄 라이센스

MIT