Windows TTS MCP Server

Claude Desktop용 Windows PowerShell 기반 Text-to-Speech 서버

🎯 개요

Windows TTS MCP Server는 Claude Desktop에서 텍스트를 음성으로 변환해주는 MCP(Model Context Protocol) 서버입니다. Windows의 내장 Speech API를 PowerShell을 통해 활용하여 안정적이고 빠른 TTS 기능을 제공합니다.

✨ 주요 특징

• 🎵 안정적인 TTS: Windows PowerShell 기반으로 스레드 안전성 확보
• ⚡ 빠른 응답: 백그라운드 재생으로 즉시 응답
• 🎛️ 다양한 옵션: 속도, 볼륨 조절 가능
• ⏹️ 완전한 제어: 재생 중지, 강제 종료, 상태 확인
• 🚨 긴급 기능: 시스템 전체 음소거
• 📦 간편한 설치: uvx로 원클릭 설치 및 실행

🚀 설치 및 실행

uvx로 실행 (권장)

# 패키지 실행
uvx windows-tts-mcp

# 개발 모드
uvx --from . tts-dev

# GitHub에서 직접 실행 (향후)
uvx --from git+https://github.com/yourusername/windows-tts-mcp windows-tts-mcp

로컬 개발

# 저장소 클론
git clone https://github.com/yourusername/windows-tts-mcp
cd windows-tts-mcp

# 로컬에서 실행
uvx --from . windows-tts-mcp

# 개발 모드
uvx --from . tts-dev

🎛️ Claude Desktop 설정

Claude Desktop의 설정 파일에 다음을 추가하세요:

{
  "mcpServers": {
    "windows-tts": {
      "command": "uvx",
      "args": ["windows-tts-mcp"]
    }
  }
}

설정 파일 위치:

• Windows: %APPDATA%\\Claude\\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/claude/claude_desktop_config.json

🎵 사용법

Claude Desktop에서 다음과 같이 요청하면 됩니다:

📢 기본 음성 재생

• "이 텍스트를 읽어줘"
• "다음 내용을 음성으로 들려줘"
• "답변을 소리로 들려줘"

⚡ 속도 조절

• "빠르게 읽어줘: [텍스트]"
• "천천히 읽어줘: [텍스트]"
• "작은 소리로 읽어줘: [텍스트]"

⏹️ 재생 제어

• "음성 중지해줘"
• "TTS 상태 확인해줘"
• "모든 음성 강제 종료해줘"
• "긴급 음소거해줘" (시스템 전체 음소거)

🛠️ 도구 목록

도구	설명	사용 예시
speak	기본 음성 재생	"이 텍스트 읽어줘"
speak_fast	빠른 속도 재생	"빠르게 읽어줘"
speak_slow	천천히 재생	"천천히 읽어줘"
speak_quiet	작은 볼륨 재생	"작게 읽어줘"
speak_short	짧은 텍스트 (100자 이하)	"짧게 말해줘"
stop_speech	음성 재생 중지	"음성 멈춰줘"
kill_all_tts	모든 TTS 강제 종료	"모든 음성 종료"
get_tts_status	재생 상태 확인	"음성 상태 확인"
emergency_silence	긴급 음소거	"긴급 음소거"
test_tts	시스템 테스트	"TTS 테스트"

🔧 기술적 세부사항

시스템 요구사항

• 운영체제: Windows 10/11
• Python: 3.11 이상
• PowerShell: 5.0 이상 (Windows 기본 포함)
• 기타: Windows Speech Platform (기본 포함)

아키텍처

Claude Desktop
    ↓ (MCP Protocol)
Windows TTS MCP Server
    ↓ (subprocess)
PowerShell
    ↓ (System.Speech)
Windows Speech API
    ↓
Audio Output

특징

• 스레드 안전성: 각 TTS 요청을 별도 스레드에서 처리
• 프로세스 관리: 실행 중인 모든 TTS 프로세스 추적 및 제어
• 오류 처리: 타임아웃, 예외 상황에 대한 견고한 처리
• 리소스 정리: 완료된 프로세스 자동 정리

🐛 문제 해결

음성이 나오지 않는 경우

1. Windows 오디오 확인

   # PowerShell에서 직접 테스트
   Add-Type -AssemblyName System.Speech
   $synth = New-Object System.Speech.Synthesis.SpeechSynthesizer
   $synth.Speak("테스트")
   

2. 볼륨 설정 확인

   • Windows 볼륨 믹서에서 PowerShell 볼륨 확인
   • 시스템 기본 오디오 장치 설정 확인

3. Speech Platform 확인

   • Windows 설정 → 시간 및 언어 → 음성
   • 음성 인식 언어 설정 확인

프로세스가 남아있는 경우

# 강제 정리
uvx windows-tts-mcp
# Claude에서 "모든 TTS 강제 종료해줘" 실행

📝 개발

프로젝트 구조

windows-tts-mcp/
├── pyproject.toml          # 패키지 설정
├── README.md               # 이 파일
├── windows_tts_mcp/        # 메인 패키지
│   ├── __init__.py
│   └── main.py            # TTS 서버 코드
├── .gitignore
└── uv.lock

개발 환경 설정

# 저장소 클론
git clone https://github.com/yourusername/windows-tts-mcp
cd windows-tts-mcp

# uv로 의존성 설치
uv sync

# 개발 모드 실행
uvx --from . tts-dev

기여하기

1. 이 저장소를 포크하세요
2. 새 브랜치를 만드세요 (git checkout -b feature/amazing-feature)
3. 변경사항을 커밋하세요 (git commit -m 'Add amazing feature')
4. 브랜치에 푸시하세요 (git push origin feature/amazing-feature)
5. Pull Request를 열어주세요

📄 라이선스

이 프로젝트는 MIT 라이선스 하에 배포됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.

🙏 감사의 말

• Anthropic - Claude와 MCP 개발
• Model Context Protocol - MCP 표준 제공
• uv - 현대적인 Python 패키지 관리

🔗 관련 링크

• Model Context Protocol 공식 문서
• Claude Desktop 다운로드
• uv 공식 문서

---

Made with ❤️ for Claude Desktop users