음성 MCP 서버
Kokoro TTS 모델을 사용하여 텍스트-음성 변환 기능을 제공하는 모델 컨텍스트 프로토콜 서버입니다.
구성
다음 환경 변수를 사용하여 서버를 구성할 수 있습니다.
| 변하기 쉬운 | 설명 | 기본 | 유효 범위 |
|---|
MCP_DEFAULT_SPEECH_SPEED | 텍스트 음성 변환을 위한 기본 속도 배수 | 1.1 | 0.5에서 2.0까지 |
커서에서:
지엑스피1
특징
- 🎯 Kokoro TTS 모델을 사용한 고품질 텍스트 음성 변환
- 🗣️ 다양한 음성 옵션 제공
- 🎛️ 사용자 정의 가능한 음성 매개변수(음성, 속도)
- 🔌 MCP 호환 인터페이스
- 📦 간편한 설치 및 설정
- 🚀 API 키가 필요하지 않습니다
설치
# Using npm
npm install speech-mcp-server
# Using pnpm (recommended)
pnpm add speech-mcp-server
# Using yarn
yarn add speech-mcp-server
용법
서버를 실행합니다:
# Using default configuration
npm start
# With custom speech speed
MCP_DEFAULT_SPEECH_SPEED=1.5 npm start
서버는 다음과 같은 MCP 도구를 제공합니다.
text_to_speech : 기본 텍스트-음성 변환text_to_speech_with_options : 사용자 정의 가능한 속도의 텍스트 음성 변환list_voices : 사용 가능한 모든 음성을 나열합니다.get_model_status : TTS 모델의 초기화 상태를 확인합니다.
개발
# Clone the repository
git clone <your-repo-url>
cd speech-mcp-server
# Install dependencies
pnpm install
# Start development server with auto-reload
pnpm dev
# Build the project
pnpm build
# Run linting
pnpm lint
# Format code
pnpm format
# Test with MCP Inspector
pnpm inspector
사용 가능한 도구
1. 텍스트 음성 변환
기본 설정을 사용하여 텍스트를 음성으로 변환합니다.
{
"type": "request",
"id": "1",
"method": "call_tool",
"params": {
"name": "text_to_speech",
"arguments": {
"text": "Hello world",
"voice": "af_bella" // optional
}
}
}
2. 텍스트_음성_변환_옵션
사용자 정의 가능한 매개변수를 사용하여 텍스트를 음성으로 변환합니다.
{
"type": "request",
"id": "1",
"method": "call_tool",
"params": {
"name": "text_to_speech_with_options",
"arguments": {
"text": "Hello world",
"voice": "af_bella", // optional
"speed": 1.0, // optional (0.5 to 2.0)
}
}
}
3. 목록_음성
텍스트 음성 변환에 사용 가능한 모든 음성을 나열합니다.
{
"type": "request",
"id": "1",
"method": "list_voices",
"params": {}
}
4. 모델 상태 가져오기
TTS 모델 초기화의 현재 상태를 확인하세요. 특히 서버를 처음 시작할 때 모델을 다운로드하고 초기화해야 하므로 유용합니다.
{
"type": "request",
"id": "1",
"method": "call_tool",
"params": {
"name": "get_model_status",
"arguments": {}
}
}
응답 예:
{
"content": [{
"type": "text",
"text": "Model status: initializing (5s elapsed)"
}]
}
가능한 상태 값:
uninitialized : 모델 초기화가 시작되지 않았습니다.initializing : 모델이 다운로드되고 초기화됩니다.ready : 모델을 사용할 준비가 되었습니다.error : 초기화 중 오류가 발생했습니다.
테스트
MCP Inspector를 사용하거나 원시 JSON 메시지를 보내어 서버를 테스트할 수 있습니다.
# List available tools
echo '{"type":"request","id":"1","method":"list_tools","params":{}}' | node dist/index.js
# List available voices
echo '{"type":"request","id":"2","method":"list_voices","params":{}}' | node dist/index.js
# Convert text to speech
echo '{"type":"request","id":"3","method":"call_tool","params":{"name":"text_to_speech","arguments":{"text":"Hello world","voice":"af_bella"}}}' | node dist/index.js
Claude Desktop과 통합
Claude Desktop과 함께 이 서버를 사용하려면 Claude Desktop 구성 파일( ~/Library/Application Support/Claude/claude_desktop_config.json )에 다음을 추가하세요.
{
"servers": {
"speech": {
"command": "npx",
"args": ["@decodershq/speech-mcp-server"]
}
}
}
기여하다
기여를 환영합니다! 풀 리퀘스트를 제출해 주세요.
특허
MIT 라이센스 - 자세한 내용은 LICENSE 파일을 참조하세요.
문제 해결
모델 초기화 문제
서버는 시작 시 자동으로 TTS 모델을 다운로드하고 초기화하려고 시도합니다. 초기화 오류가 발생하는 경우:
- 서버는 시도 사이에 정리 작업을 거쳐 최대 3회까지 자동으로 재시도합니다.
get_model_status 도구를 사용하여 초기화 진행 상황과 오류를 모니터링합니다.- 모든 재시도 후에도 초기화가 실패하면 모델 파일을 수동으로 제거해보세요.
# Remove model files (MacOS/Linux)
rm -rf ~/.npm/_npx/**/node_modules/@huggingface/transformers/.cache/onnx-community/Kokoro-82M-v1.0-ONNX/onnx/model_quantized.onnx
rm -rf ~/.cache/huggingface/transformers/onnx-community/Kokoro-82M-v1.0-ONNX/onnx/model_quantized.onnx
# Then restart the server
npm start
이제 get_model_status 도구는 응답에 재시도 정보를 포함합니다.
{
"content": [{
"type": "text",
"text": "Model status: initializing (5s elapsed, retry 1/3)"
}]
}