AI 음성 생성 MCP 서버 유사

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

특징

Resemble AI의 음성을 사용하여 텍스트에서 음성 오디오를 생성합니다.
사용 가능한 음성 모델 나열
오디오를 로컬 파일 또는 base64로 인코딩된 문자열로 반환합니다.
다양한 연결 방법:
- SSE 전송 - 네트워크 기반 서버 전송 이벤트(기본값)
- StdIO Transport - 직접 프로세스 통신

설치 지침

필수 조건

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 운송 연결

설정 → AI → MCP 서버로 이동하세요.
"서버 추가"를 클릭하세요
연결 유형으로 "SSE"를 선택하세요
URL을 http://localhost:8083/sse 로 설정하세요.

StdIO 전송 연결

설정 → AI → MCP 서버로 이동하세요.
"서버 추가"를 클릭하세요
연결 유형으로 "하위 프로세스"를 선택하세요
명령을 python -m src.cli --implementation stdio 로 설정합니다.
선택적으로 환경 변수를 추가합니다.
- 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가 서버에 연결할 수 없는 경우:

서버가 실행 중인지 확인하세요
올바른 URL이 구성되었는지 확인하세요
API 키가 유효한지 확인하세요
서버 로그에서 오류를 찾아보세요

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

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

Python 3.10+ 환경 만들기
필요한 모든 종속성을 설치하세요
템플릿 .env 파일 설정
오디오 파일의 출력 디렉토리를 만듭니다.

수동 설치

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

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
종속성 설치:
pip install uvicorn fastapi python-dotenv requests pydantic httpx sse-starlette pip install git+https://github.com/modelcontextprotocol/python-sdk.git
환경 변수를 설정하세요.
cp .env.example .env
.env 파일을 편집하고 Resemble AI API 키를 추가하세요.
RESEMBLE_API_KEY=your_api_key_here
선택 사항: 오디오 출력 설정 사용자 정의
OUTPUT_DIR=./output AUDIO_FORMAT=mp3
출력 디렉토리 생성:
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 음성 생성 서버와 상호 작용할 수 있습니다.

커서에서 설정 → AI → MCP 서버로 이동합니다.
"서버 추가"를 클릭하고 SSE URL을 입력하세요: http://localhost:8083/sse (필요한 경우 포트를 조정하세요)
구성을 저장합니다

🔌 Claude Desktop과 통합

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

Integrations

AI 음성 생성 MCP 서버 유사

특징

설치 지침

필수 조건

환경 설정

옵션 1: Conda 사용(권장)

옵션 2: 가상 환경 사용

구성

서버 실행

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

CLI를 직접 사용하기

Claude Desktop에 연결

SSE 운송 연결

StdIO 전송 연결

커서에 연결

SSE 운송 연결

StdIO 전송 연결

사용 가능한 도구

list_voices

generate_tts

구현 세부 사항

문제 해결

MCP SDK 가져오기 오류

연결 문제

StdIO 대 SSE 전송

예시

📁 저장소 구조

🚀 빠른 설정

Conda 사용(권장)

Python venv 사용하기

수동 설치

🚀 서버 실행

🔌 커서 AI와 통합

🔌 Claude Desktop과 통합

🛠️ 도구 문서

목록_음성

생성_tts

💬 예시 프롬프트

⚠️ 문제 해결

📚 추가 문서

📄 라이센스

`list_voices`

`generate_tts`