whisper-telegram-mcp

전사하고 말하기 — 텔레그램을 통한 Claude용 양방향 음성 기능

텔레그램을 통해 Claude에게 양방향 음성 기능을 제공하는 MCP 서버입니다: Whisper로 수신된 음성 메시지를 전사하고, 합성된 음성으로 답장합니다. Claude Desktop, Claude Code 및 모든 MCP 호환 클라이언트와 작동합니다.

주요 기능

로컬 오디오 파일 전사 -- OGG, WAV, MP3, FLAC 등 지원
텔레그램 음성 메시지 전사 -- file_id를 전달하여 텍스트로 변환
텍스트를 음성 메모로 말하기 -- 음성을 합성하여 OGG로 전송 (텔레그램에서 음성 메모로 재생)
두 가지 전사 백엔드 -- 로컬 faster-whisper (무료, 비공개) 또는 OpenAI Whisper API (클라우드)
자동 모드 -- 로컬을 먼저 시도하고 실패 시 OpenAI로 전환
언어 감지 -- 자동 또는 ISO-639-1 코드 지정 가능
단어 단위 타임스탬프 -- 선택적 정밀 타이밍

사전 요구 사항

기능	요구 사항
전사 (로컬)	없음 — `[local]` 옵션을 통해 faster-whisper 번들 제공
전사 (클라우드)	`OPENAI_API_KEY` 환경 변수
음성 답장 — Kokoro (최고 품질)	Docker — `docker run -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-cpu:latest` 실행
음성 답장 — OpenAI TTS (대체)	`OPENAI_API_KEY` 환경 변수
음성 답장 — macOS say (최후의 수단)	Mac 전용, 설정 불필요

Kokoro는 Docker가 필요합니다. Docker가 실행 중이지 않으면 음성 답장은 자동으로 OpenAI TTS 또는 macOS say로 대체됩니다.

빠른 시작

Claude Code로 30초 만에 설정하기

가장 빠른 시작 방법 — Claude Code에게 설정을 요청하세요:

.mcp.json (Claude Code) 또는 claude_desktop_config.json (Claude Desktop)에 추가:

{
  "mcpServers": {
    "whisper-telegram-mcp": {
      "command": "uvx",
      "args": ["whisper-telegram-mcp"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your-bot-token-here"
      }
    }
  }
}

Claude를 재시작하고 다음과 같이 말하세요: "Set up my Telegram bot for voice transcription" — Claude가 BotFather를 통한 봇 생성 및 모든 설정 과정을 안내합니다.

`uvx`를 사용한 한 줄 명령

uvx whisper-telegram-mcp

설치가 필요 없습니다 -- uvx가 모든 것을 처리합니다.

또는 pip로 설치

pip install "whisper-telegram-mcp[all]"
whisper-telegram-mcp

텔레그램 봇 설정

텔레그램을 열고 @BotFather에게 메시지를 보냅니다.
/newbot을 보내고 안내에 따라 봇을 생성합니다.
토큰을 복사합니다 (예: 1234567890:ABCdef...).
MCP 설정 환경 변수에 TELEGRAM_BOT_TOKEN을 추가합니다 (아래 참조).
봇에게 메시지를 보내 시작하세요 — 승인된 사용자에게만 응답합니다.

Claude 텔레그램 플러그인이 액세스 제어를 처리합니다. 페어링/허용 목록 설정은 해당 문서를 참조하세요.

통합

Claude Desktop

Claude Desktop 설정(~/Library/Application Support/Claude/claude_desktop_config.json)에 추가:

{
  "mcpServers": {
    "whisper-telegram-mcp": {
      "command": "uvx",
      "args": ["whisper-telegram-mcp"],
      "env": {
        "WHISPER_MODEL": "base",
        "WHISPER_BACKEND": "auto",
        "TELEGRAM_BOT_TOKEN": "your-bot-token-here"
      }
    }
  }
}

Claude Code

프로젝트의 .mcp.json에 추가:

{
  "mcpServers": {
    "whisper-telegram-mcp": {
      "command": "uvx",
      "args": ["whisper-telegram-mcp"],
      "env": {
        "WHISPER_MODEL": "base",
        "WHISPER_BACKEND": "auto",
        "TELEGRAM_BOT_TOKEN": "your-bot-token-here"
      }
    }
  }
}

도구

도구	설명
`transcribe_audio`	로컬 오디오 파일(OGG, WAV, MP3 등)을 텍스트로 전사
`transcribe_telegram_voice`	`file_id`를 통해 텔레그램 음성 메시지를 다운로드 및 전사
`speak_text`	텍스트를 음성으로 변환 → OGG/Opus 파일 (텔레그램에서 음성 메모로 재생)
`list_models`	속도/정확도 정보와 함께 사용 가능한 Whisper 모델 크기 나열
`check_backends`	사용 가능하고 설정된 백엔드(로컬/OpenAI) 확인

`transcribe_audio`

file_path: str        # Absolute path to audio file
language: str | None  # ISO-639-1 code (e.g. "en"), None = auto-detect
word_timestamps: bool # Include word-level timestamps (default: false)

`transcribe_telegram_voice`

file_id: str          # Telegram voice message file_id
bot_token: str | None # Bot token (falls back to TELEGRAM_BOT_TOKEN env var)
language: str | None  # ISO-639-1 code, None = auto-detect
word_timestamps: bool # Include word-level timestamps (default: false)

`speak_text`

텍스트를 OGG/Opus 오디오 파일로 변환합니다. 사용 가능한 최상의 TTS 백엔드를 자동으로 선택합니다.

text: str             # Text to synthesise
voice: str            # Voice name (default: "af_sky")
output_path: str|None # Optional path for output .ogg file

TTS 백엔드 (우선순위 순):

백엔드	비용	품질	설정
Kokoro (로컬)	무료	자연스러움, 고품질	수동 시작 (아래 참조)
OpenAI TTS (클라우드)	~$0.015/1k 문자	고품질	`OPENAI_API_KEY` 환경 변수
macOS say (대체)	무료	로봇 음성	Mac 전용, 설정 불필요

auto 모드(기본값)에서는 서버가 Kokoro를 먼저 시도한 다음 OpenAI, 마지막으로 macOS say를 시도합니다. TTS_BACKEND 환경 변수로 설정하세요.

Kokoro 로컬 시작:

Kokoro FastAPI는 PyPI에 없으므로 MCP 서버를 실행하기 전에 시작하세요:

# Docker (simplest, recommended)
docker run -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-cpu:latest

# Apple Silicon (GPU-accelerated)
docker run -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-gpu-mac:latest

# From source
git clone https://github.com/remsky/Kokoro-FastAPI && cd Kokoro-FastAPI && ./start-cpu.sh

실행되면 MCP 서버가 http://127.0.0.1:8880/v1에서 자동으로 감지합니다. KOKORO_BASE_URL 환경 변수로 재정의할 수 있습니다.

Kokoro 음성 (기본):

음성	억양	스타일
`af_sky`	미국	여성 (기본값)
`af_bella`	미국	여성
`af_sarah`	미국	여성
`af_nicole`	미국	여성
`am_adam`	미국	남성
`am_michael`	미국	남성
`bf_emma`	영국	여성
`bf_isabella`	영국	여성
`bm_george`	영국	남성
`bm_lewis`	영국	남성

OpenAI 음성 (대체):

음성	스타일
`alloy`	중립
`echo`	남성
`fable`	내레이션
`onyx`	낮은 남성
`nova`	여성
`shimmer`	부드러운 여성

Kokoro 음성 이름은 대체 시 가장 가까운 OpenAI 또는 macOS 음성으로 자동 매핑됩니다.

반환값:

{
  "file_path": "/tmp/tmpXXX.ogg",
  "size_bytes": 16555,
  "backend": "kokoro",
  "voice": "af_sky",
  "success": true,
  "error": null
}

반환된 file_path를 텔레그램 첨부 파일로 보내면 기본 음성 메모로 나타납니다.

전사 응답 형식

모든 전사 도구는 다음을 반환합니다:

{
  "text": "Hello, this is a voice message.",
  "language": "en",
  "language_probability": 0.98,
  "duration": 3.5,
  "segments": [
    {"start": 0.0, "end": 3.5, "text": "Hello, this is a voice message."}
  ],
  "backend": "local",
  "success": true,
  "error": null
}

설정

모든 설정은 환경 변수를 통해 이루어집니다:

변수	기본값	설명
`WHISPER_BACKEND`	`auto`	`auto`, `local`, 또는 `openai`
`WHISPER_MODEL`	`base`	Whisper 모델 크기 (아래 참조)
`OPENAI_API_KEY`	--	`openai` 전사 및 TTS 백엔드에 필요
`TELEGRAM_BOT_TOKEN`	--	`transcribe_telegram_voice`에 필요
`WHISPER_LANGUAGE`	자동 감지	ISO-639-1 언어 코드
`TTS_BACKEND`	`auto`	`auto`, `kokoro`, `openai`, 또는 `macos`
`TTS_VOICE`	`af_sky`	`speak_text`용 기본 음성 (Kokoro 음성 이름)
`KOKORO_BASE_URL`	`http://127.0.0.1:8880/v1`	Kokoro FastAPI 기본 URL

작동 원리

                         MCP Client (Claude)
                              |
                         [MCP stdio]
                              |
                    whisper-telegram-mcp
                    /         |         \
                   /          |          \
      transcribe_audio  transcribe_     speak_text
                        telegram_voice      |
              |               |          auto_tts()
              |         [Bot API DL]    /    |    \
              +--------+------+     Kokoro OpenAI macOS
                       |            (local) (cloud) (say)
                 auto_transcribe()      |
                  /           \      .ogg file
           LocalBackend    OpenAIBackend
           (faster-whisper)  (Whisper API)

Claude가 MCP(stdio 전송)를 통해 도구 호출을 보냅니다.
텔레그램 음성 메시지의 경우, Bot API를 통해 파일이 다운로드됩니다.
auto_transcribe()가 사용 가능한 최상의 전사 백엔드를 선택합니다.
auto_tts()가 사용 가능한 최상의 TTS 백엔드를 선택합니다 (Kokoro -> OpenAI -> macOS).
결과가 구조화된 JSON으로 반환됩니다.

로컬 vs OpenAI

	로컬 (faster-whisper)	OpenAI API
비용	무료	$0.006/분
개인정보	모든 데이터가 기기에 유지됨	오디오가 OpenAI로 전송됨
속도	모델에 따라 약 1-10초	약 1-3초
설정	자동 (첫 사용 시 모델 다운로드)	`OPENAI_API_KEY` 필요
정확도	`base` 이상에서 우수	우수
오프라인	예	아니오

모델 크기

모델	파라미터	속도	정확도	VRAM
`tiny`	39M	가장 빠름	가장 낮음	~1GB
`base`	74M	빠름	좋음	~1GB
`small`	244M	보통	더 좋음	~2GB
`medium`	769M	느림	높음	~5GB
`large-v3`	1550M	가장 느림	가장 높음	~10GB
`turbo`	~800M	빠름	높음	~6GB

영어 전용 변형(tiny.en, base.en, small.en, medium.en)은 영어에 대해 약간 더 정확합니다.

개인정보 및 데이터

로컬 백엔드 (faster-whisper): 오디오가 기기에 유지됩니다. 어떤 데이터도 외부로 나가지 않습니다.
OpenAI 백엔드: 오디오는 OpenAI의 데이터 보존 정책에 따라 OpenAI API로 전송됩니다.
임시 파일: 텔레그램에서 다운로드된 오디오는 /tmp에 기록되며 전사 직후 즉시 삭제됩니다.
로그: stderr로만 출력됩니다 — 오디오 콘텐츠나 자격 증명은 절대 기록되지 않습니다.

개발

git clone https://github.com/abid-mahdi/whisper-telegram-mcp.git
cd whisper-telegram-mcp
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Run unit tests
pytest tests/ -v -m "not integration"

# Run integration tests (downloads ~150MB model on first run)
pytest tests/ -m integration -v

# Run with coverage
pytest tests/ --cov=src/whisper_telegram_mcp --cov-report=term-missing

MCP Inspector

uvx mcp dev src/whisper_telegram_mcp/server.py

기여

저장소를 포크합니다.
기능 브랜치를 생성합니다 (git checkout -b feat/amazing-feature).
테스트를 실행합니다 (pytest tests/ -v -m "not integration").
커밋 규칙을 준수하여 커밋합니다 (feat:, fix:, docs: 등).
풀 리퀘스트를 엽니다.

라이선스

MIT

whisper-telegram-mcp

whisper-telegram-mcp

주요 기능

사전 요구 사항

빠른 시작

Claude Code로 30초 만에 설정하기

`uvx`를 사용한 한 줄 명령

또는 pip로 설치

텔레그램 봇 설정

통합

Claude Desktop

Claude Code

도구

`transcribe_audio`

`transcribe_telegram_voice`

`speak_text`

전사 응답 형식

설정

작동 원리

로컬 vs OpenAI

모델 크기

개인정보 및 데이터

개발

MCP Inspector

기여

라이선스

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API

whisper-telegram-mcp

주요 기능

사전 요구 사항

빠른 시작

Claude Code로 30초 만에 설정하기

uvx를 사용한 한 줄 명령

또는 pip로 설치

텔레그램 봇 설정

통합

Claude Desktop

Claude Code

도구

transcribe_audio

transcribe_telegram_voice

speak_text

전사 응답 형식

설정

작동 원리

로컬 vs OpenAI

모델 크기

개인정보 및 데이터

개발

MCP Inspector

기여

라이선스

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API

`uvx`를 사용한 한 줄 명령

`transcribe_audio`

`transcribe_telegram_voice`

`speak_text`