Voicevox MCP 서버

VOICEVOX 호환 음성 합성 서버(AivisSpeech/VOICEVOX/COEIROINK)를 MCP(Model Context Protocol)를 통해 이용하기 위한 서버입니다. Cursor등에서의 Claude 3.7을 사용한 에이전트 모드에서의 음성 합성에 이용할 수 있습니다.

요건

Windows 환경

Node.js 18 이상
VOICEVOX ENGINE 등 (로컬 http://localhost : 50000 등에서 실행 )
VLC 미디어 플레이어(경로가 통과함)

Docker 환경(WSL2)

Docker 및 Docker Compose
WSL2
VOICEVOX ENGINE 등 (로컬 또는 Docker에서 실행)
sudo apt install libsdl2-dev pulseaudio-utils pulseaudio 된 Linux 환경
/mnt/wslg 에 대한 액세스 권한

설치 및 설정

리포지토리 복제

git clone https://github.com/Dosugamea/voicevox-mcp-server.git
cd voicevox-mcp-server

종속성 설치

npm install

환경 변수 설정 .env_example 을 복사하여 .env 파일을 만들고 필요에 따라 설정을 변경합니다.

VOICEVOX_API_URL=http://localhost:50021
VOICEVOX_SPEAKER_ID=1

실행 방법

Windows 환경에서 실행

에디터와 별도로 아래 절차에 따라 서버를 시작하십시오.

npm run build
npm start

Docker 환경에서 실행

에디터와 별도로의 조작은 불필요합니다. stdio 모드에서 상승하기 때문에 직접 실행할 수 없습니다.

설정 방법

Windows 환경에서 실행하는 경우

mcp.json에 다음을 추가하십시오. 연결이 불안정하기 때문에 연결이 끊어지면 다시 연결하십시오.

        "voicevox": {
            "url": "http://localhost:10100/sse"
        }

Docker 환경에서 실행하는 경우

mcp.json에 다음을 추가하십시오. (작가 환경에서의 동작은 확인할 수 없습니다)

{
    "tools": {
        "voicevox": {
            "command": "cmd",
            "args": [
                "/c",
                "docker",
                "run",
                "-i",
                "--rm",
                "-v",
                "/mnt/wslg:/mnt/wslg",
                "-e",
                "PULSE_SERVER",
                "-e",
                "SDL_AUDIODRIVER",
                "-e",
                "VOICEVOX_API_URL",
                "-e",
                "VOICEVOX_SPEAKER_ID",
                "your-local-docker-image-name"
            ],
            "env": {
                "PULSE_SERVER": "unix:/mnt/wslg/PulseServer",
                "SDL_AUDIODRIVER": "pulseaudio",
                "VOICEVOX_API_URL": "http://host.docker.internal:50031",
                "VOICEVOX_SPEAKER_ID": "919692871"
            }
        }
    }
}

스피커 ID 정보

스피커 ID는 사용하는 VOICEVOX 모델에 따라 다릅니다. 기본적으로 "1"(시코쿠 메탄)을 사용합니다. 다른 화자 ID를 사용하는 경우 환경 변수 VOICEVOX_SPEAKER_ID 를 변경합니다.

화자 ID 목록은 VOICEVOX ENGINE API의 /speakers 엔드포인트에서 확인할 수 있습니다. 예: curl http://localhost:50021/speakers

문제해결

VOICEVOX와의 연결 오류 : VOICEVOX ENGINE이 실행 중이고 API URL이 올바르게 설정되어 있는지 확인하십시오.
오디오가 재생되지 않음 : VLC가 올바르게 설치되어 있고 경로가 통과하는지 확인합니다.
Docker 환경에서 오디오 출력 문제 : pulseaudio 설정이 올바른지 확인하십시오.

개발자를 위한 정보

소스 코드에 기여하는 경우 Issue를 작성하거나 Pull Request를 제출하십시오.
버그 보고 및 기능 요청은 GitHub의 Issue 기능을 이용해 주십시오.

라이센스

MIT License

Voicevox MCP Server

Integrations