livechat-mcp

AI 코딩 어시스턴트와 지속적인 음성 대화를 나눌 수 있게 해주는 MCP(Model Context Protocol) 서버입니다. 사용자가 말하면 Whisper를 통해 로컬에서 음성이 텍스트로 변환되며, 각 발화는 마치 직접 타이핑한 것처럼 어시스턴트에게 전달됩니다. 탭 전환, 복사/붙여넣기, 일괄 녹음이 필요 없습니다.

모든 MCP 호스트에서 작동합니다. 다음 호스트를 우선적으로 지원합니다:

• Claude Code

• Codex CLI

• Gemini CLI

요구 사항

• macOS, Linux, 또는 Windows (PowerShell을 통한 네이티브, 또는 WSL2 / Git Bash 환경).

• Python 3.10+

• 설치된 MCP 호스트 (Claude Code, Codex, Gemini 등)

• 작동하는 마이크

• Whisper 모델 캐시 및 종속성 설치를 위한 약 500MB의 디스크 공간

• 프로젝트 관리를 위한 uv (권장)

빠른 설치 (권장)

저장소를 복제한 후:

# macOS / Linux / Git Bash on Windows
./install.sh

# Native Windows PowerShell
.\install.ps1

부트스트랩은 OS를 감지하고, 필요한 경우 portaudio를 설치하며(brew / apt / dnf / pacman / zypper — Windows 휠은 번들로 제공됨), uv가 없으면 설치하고, uv sync를 실행한 뒤 ~/.local/bin에 마법사를 배치하고 대화형 설정 마법사를 실행합니다.

Windows: 네이티브 잠금은 msvcrt를 사용하고 테이크오버 신호는 파일 기반이므로 fcntl 종속성이 없습니다. 대화형 마법사는 bash 스크립트입니다. install.ps1은 Git Bash를 통해 이를 호출하며, Git Bash가 없으면 winget을 통해 설치를 제안합니다.

수동 설정

단계별로 설치하려면 install.sh가 수행하는 작업은 다음과 같습니다:

1. portaudio 설치

sounddevice는 portaudio가 필요합니다.

• macOS: brew install portaudio

• Debian/Ubuntu: sudo apt-get install libportaudio2 portaudio19-dev

• Fedora/RHEL: sudo dnf install portaudio portaudio-devel

• Arch: sudo pacman -S portaudio

2. uv가 없는 경우 설치

curl -LsSf https://astral.sh/uv/install.sh | sh

3. 복제 및 종속성 설치

cd livechat-mcp
uv sync

이 작업은 .venv/를 생성하고 mcp, faster-whisper, sounddevice, silero-vad, torch 등을 설치합니다.

4. 설정 마법사 실행

install -m 0755 bin/livechat-mcp ~/.local/bin/livechat-mcp
livechat-mcp setup

마법사는 다음을 수행합니다:

1. 설치할 어시스턴트(Claude Code / Codex / Gemini, 조합 가능)를 묻습니다.

2. 사용자 지정 슬래시 명령을 지원하는 호스트에 /livechat 및 /endlivechat 슬래시 명령을 복사합니다. Codex의 경우, 현재 Codex CLI 릴리스가 사용자 지정 프롬프트를 /livechat으로 노출하지 않기 때문에 레거시 프롬프트 파일과 livechat 스킬을 모두 설치합니다.

3. 각 호스트의 구성 파일에 MCP 서버를 등록합니다.

4. 조정 가능한 환경 변수(무음 임계값, Whisper 모델 등)를 안내합니다. 기본값을 유지하려면 Enter를 누르세요.

~/.local/bin이 PATH에 있는지 확인하세요(공식 uv 설치 프로그램을 사용했다면 이미 포함되어 있습니다).

직접 설정하려면 각 호스트에 대한 수동 단계가 아래에 있습니다.

5. 마이크 권한 부여

• macOS: 서버가 처음으로 오디오 캡처를 시도할 때, macOS는 터미널 앱(Terminal, iTerm, Ghostty, Warp 등)에 마이크 액세스 권한을 요청합니다. 프롬프트를 놓친 경우 수동으로 활성화하세요:

  시스템 설정 → 개인정보 보호 및 보안 → 마이크 → 터미널 앱 활성화

  이 단계를 건너뛰면 오디오 캡처가 조용히 무음으로 반환되며 아무것도 변환되지 않습니다.

• Windows: 설정 → 개인정보 및 보안 → 마이크 → 데스크톱 앱이 마이크에 액세스하도록 허용(터미널이 허용되어 있는지 확인).

• Linux: 일반적으로 프롬프트가 없습니다. 사용자가 올바른 ALSA / PulseAudio / Pipewire 액세스 권한(일반적으로 audio 그룹)을 가지고 있는지 확인하세요.

6. Whisper 모델 사전 다운로드 (선택 사항)

첫 실행 시 base.en(~150MB)을 다운로드합니다. 미리 준비할 수 있습니다:

uv run python -c "from faster_whisper import WhisperModel; WhisperModel('base.en', device='cpu', compute_type='int8')"

수동 설치 (livechat-mcp setup을 사용한 경우 건너뛰기)

Claude Code

슬래시 명령 복사:

mkdir -p ~/.claude/commands
cp commands/livechat.md ~/.claude/commands/
cp commands/endlivechat.md ~/.claude/commands/

MCP 서버 등록:

claude mcp add livechat -- uv --directory "$(pwd)" run livechat-mcp

또는 ~/.claude.json을 직접 편집:

{
  "mcpServers": {
    "livechat": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/livechat-mcp", "run", "livechat-mcp"]
    }
  }
}

Codex CLI

Codex 스킬 및 레거시 프롬프트 파일 설치:

mkdir -p ~/.codex/skills/livechat
cp skills/livechat/SKILL.md ~/.codex/skills/livechat/
mkdir -p ~/.codex/prompts
cp commands/livechat.md ~/.codex/prompts/
cp commands/endlivechat.md ~/.codex/prompts/

~/.codex/config.toml에 MCP 서버 등록:

[mcp_servers.livechat]
command = "uv"
args = ["--directory", "/absolute/path/to/livechat-mcp", "run", "livechat-mcp"]

Gemini CLI

Gemini는 사용자 지정 명령에 TOML을 사용합니다. 마법사가 이를 생성합니다. 수동으로 하려면 commands/gemini/livechat.toml.template을 참조하세요(livechat-mcp setup을 한 번 실행하면 생성됨).

~/.gemini/settings.json에 MCP 서버 등록:

{
  "mcpServers": {
    "livechat": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/livechat-mcp", "run", "livechat-mcp"]
    }
  }
}

사용법

터미널에서 어시스턴트의 CLI를 엽니다:

claude    # or: codex    or: gemini

그런 다음 어시스턴트 프롬프트에서:

/livechat            # Claude Code, Gemini CLI
use livechat         # Codex CLI

Codex 재시작 필요. Codex는 시작 시에만 스킬과 MCP 서버를 로드합니다. Codex가 열려 있는 동안 마법사를 실행했다면, use livechat을 사용하기 전에 종료하고 다시 시작하세요.

Codex 0.128.0은 사용자가 정의한 /livechat 슬래시 명령을 지원하지 않습니다. /는 현재 Codex의 내장 명령을 위해 예약되어 있습니다. 설정 시 검색 가능한 livechat 스킬이 설치되므로 use livechat을 입력하거나 /skills를 열어 livechat을 선택할 수 있습니다.

어시스턴트가 get_voice_input을 호출하고 듣기 시작합니다. 평소처럼 말하세요. 약 1.5초 동안 멈추면 발화가 완료되고, 변환되어 프롬프트로 전송됩니다. 어시스턴트가 응답한 후 즉시 다음 발화를 듣습니다.

어시스턴트가 응답을 생성하는 동안에도 마이크는 계속 켜져 있습니다. 그동안 말하는 내용은 대기열에 추가되었다가 다음 get_voice_input 호출 시 한꺼번에 전달됩니다.

세션 종료

세 가지 방법:

1. /endlivechat — 가장 깔끔하며 어시스턴트 프롬프트에서 실행됩니다. (응답 중간이라면 먼저 현재 턴을 중단해야 합니다.)

2. 웨이크 문구 — terminate voice session now라고 말합니다. 변환 결과가 종료를 트리거합니다. 이 문구는 실제 검토 내용과 충돌하지 않도록 의도적으로 어색하게 설정되었습니다. LIVECHAT_END_PHRASE를 통해 구성 가능합니다.

3. Ctrl+C — MCP 서버를 종료합니다. 어시스턴트는 다음 호출 시 도구 오류를 확인하고 루프를 중단합니다.

구성

모든 조정 가능한 설정은 livechat_mcp/config.py에 있으며 환경 변수를 통해 재정의할 수 있습니다:

설정하는 가장 쉬운 방법은 livechat-mcp set KEY VALUE를 사용하는 것입니다. 이는 발견된 모든 호스트 구성(Claude / Codex / Gemini)의 env 블록을 편집합니다.

livechat-mcp show           # print current env block(s)
livechat-mcp set LIVECHAT_SILENCE_SEC 1.5
livechat-mcp unset LIVECHAT_DEBUG

변경 후 어시스턴트 CLI를 재시작하세요. MCP 환경 변수는 서버 시작 시 읽힙니다.

수동으로 하려면 각 호스트 구성에서 livechat MCP 항목의 env 필드를 편집하세요. Claude Code 예시:

{
  "mcpServers": {
    "livechat": {
      "command": "uv",
      "args": ["--directory", "/abs/path", "run", "livechat-mcp"],
      "env": {
        "LIVECHAT_WHISPER_MODEL": "small.en",
        "LIVECHAT_DEBUG": "1"
      }
    }
  }
}

문제 해결

말해도 아무 일도 일어나지 않습니다. 다음 순서로 확인하세요: 터미널 앱의 마이크 권한, 마이크 입력 레벨(시스템 설정 → 사운드), LIVECHAT_DEBUG=1로 설정하고 stderr에서 VAD 이벤트를 확인, LIVECHAT_VAD_THRESHOLD를 0.3으로 낮추기.

변환이 부정확합니다. 모델 업그레이드: LIVECHAT_WHISPER_MODEL=small.en 또는 medium.en. medium.en은 CPU에서 눈에 띄게 느리지만(여전히 실시간에 가까움) 기술 용어에 훨씬 더 좋습니다.

발화가 너무 빨리/느리게 종료됩니다. LIVECHAT_SILENCE_SEC를 조정하세요(또는 livechat-mcp set LIVECHAT_SILENCE_SEC 1.5 실행). 1.0~4.5초가 유용한 범위입니다. 낮을수록 반응이 빠르지만 생각하는 도중의 멈춤을 끊을 위험이 있습니다.

uv를 찾을 수 없습니다. uv를 설치하거나(권장), MCP 구성 command를 활성화된 venv 내부에서 python -m livechat_mcp.server를 직접 호출하도록 변경하세요.

서버는 시작되지만 어시스턴트가 도구를 호출하지 않습니다. /livechat이 호출되었는지 확인하세요. 슬래시 명령 없이는 어시스턴트가 루프에 진입할 지시를 받지 못합니다.

서버 로그가 어시스턴트 UI에 쓰레기 값으로 표시되거나 프로토콜을 깨뜨립니다. 이런 일은 발생하지 않아야 합니다. 모든 서버 로깅은 stderr로 전달됩니다. 만약 표시된다면 버그를 보고하세요. file=sys.stderr 없이 print(...) 문을 추가하지 않았는지 확인하세요.

시작 시 portaudio 오류가 발생합니다. 설치하세요: brew install portaudio. 설치되어 있는데도 실패하면 brew reinstall portaudio를 시도하고 sounddevice를 재설치하세요: uv sync --reinstall.

작동 원리 (요약)

[mic] → [Silero VAD] → [Whisper] → [queue] ← [get_voice_input tool] ← [Assistant]
   ↑________background thread, always running________↑

오디오 파이프라인은 MCP 도구와 분리되어 있으므로 서버가 켜져 있는 동안 마이크는 항상 활성화되어 있습니다. 어시스턴트가 응답을 생성하는 동안 말한 발화는 대기열에 저장되었다가 다음 도구 호출 시 전달됩니다.

라이선스

MIT.