convez.ai
MCP ServerIntegração & APIsIntermediário
Hakanai-AI

Agent Voice MCP

Hakanai-AI/agent-voice-mcp

STT/TTS local autossuficiente para Claude Code com Whisper e Kokoro

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP local de fala-para-texto e texto-para-fala para Claude Code. Integra Whisper.cpp (STT) e Kokoro (TTS) com suporte a múltiplos formatos de áudio e vozes, sem custos de API.

Instalação

$npx convez-ai Hakanai-AI/agent-voice-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
37%
Último commit
há 5 dias
Versão
—
Issues abertas
1
Contribuidores
2

Casos de uso

  • Transcrição de áudio em tempo real sem API externa
  • Síntese de fala com múltiplas vozes para automações
  • Integração de entrada/saída de voz em agentes Claude
  • Processamento de áudio em infraestrutura própria (ARM Linux)

Veredito

MCP robusto e bem documentado para quem precisa de STT/TTS offline. Excelente para automatizar workflows com áudio mantendo dados locais, mas requer setup de serviços backend (Whisper e Kokoro) antes de funcionar.

README

A tradução para o português deste README ainda está na fila.

agent-voice-mcp

Local Speech-to-Text and Text-to-Speech MCP Server for Claude Code.

Provides file-based audio transcription and speech synthesis tools via the Model Context Protocol, powered by Whisper.cpp (STT) and Kokoro (TTS).

Self-hosted, zero API cost, ARM Linux compatible.

Features

  • transcribe — Convert audio files to text (wav, mp3, m4a, ogg, webm, flac, aac)
  • speak — Convert text to audio files (MP3) with multiple voices
  • health — Check STT/TTS service status
  • Connects to any OpenAI-compatible STT/TTS API endpoints
  • Configurable via environment variables
  • Works on x86 and ARM Linux, macOS

Quick Start

1. Install STT/TTS Services

The easiest way to get Whisper and Kokoro running:

# Using VoiceMode's service manager (recommended)
uvx voice-mode service install whisper
uvx voice-mode service install kokoro
uvx voice-mode service start whisper
uvx voice-mode service start kokoro

Or run them manually:

2. Add to Claude Code

Add to your ~/.claude.json:

{
  "mcpServers": {
    "voice": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/agent-voice-mcp", "python", "server.py"],
      "env": {
        "WHISPER_URL": "http://localhost:2022",
        "KOKORO_URL": "http://localhost:8880"
      }
    }
  }
}

Or with a virtual environment:

{
  "mcpServers": {
    "voice": {
      "type": "stdio",
      "command": "/path/to/agent-voice-mcp/.venv/bin/python",
      "args": ["/path/to/agent-voice-mcp/server.py"],
      "env": {
        "WHISPER_URL": "http://localhost:2022",
        "KOKORO_URL": "http://localhost:8880"
      }
    }
  }
}

3. Install Dependencies

cd agent-voice-mcp
uv venv && uv pip install mcp

Tools

transcribe

Transcribe an audio file to text using local Whisper.

ParameterTypeRequiredDescription
file_pathstringYesAbsolute path to the audio file
languagestringNoLanguage hint (e.g. en, zh, ja). Auto-detected if omitted.

Example:

transcribe(file_path="/path/to/audio.m4a")
→ "This is a test recording."

transcribe(file_path="/path/to/chinese.mp3", language="zh")
→ "你好,這是測試錄音。"

speak

Convert text to speech using local TTS.

ParameterTypeRequiredDescription
textstringYesText to convert to speech
voicestringNoVoice name (default: af_sky)
speednumberNoSpeech speed 0.5-2.0 (default: 1.0)

Available voices:

  • af_sky — Female (default)
  • af_bella — Female
  • am_adam — Male
  • am_michael — Male
  • See Kokoro documentation for full voice list

Example:

speak(text="Hello, world!")
→ "Audio saved: ~/.agent-voice-mcp/output/tts-1234567890.mp3 (42.3 KB)"

health

Check the status of both services.

health()
→ "Whisper STT: ✅ healthy (http://localhost:2022)
   Kokoro TTS: ✅ healthy (http://localhost:8880)"

Configuration

All configuration via environment variables:

VariableDefaultDescription
WHISPER_URLhttp://localhost:2022Whisper.cpp server URL
KOKORO_URLhttp://localhost:8880Kokoro TTS server URL
VOICE_OUTPUT_DIR~/.agent-voice-mcp/outputDirectory for generated audio files
TRANSCRIBE_TIMEOUT120Transcription timeout in seconds
SPEAK_TIMEOUT60TTS timeout in seconds
DEFAULT_VOICEaf_skyDefault TTS voice
DEFAULT_SPEED1.0Default speech speed

Use Cases

Channel Voice Messages

Integrate with Discord or LINE channel plugins to auto-transcribe voice messages:

User sends voice message → Channel plugin downloads audio
→ transcribe(file_path) → Deliver transcript to Claude session

Meeting Transcription

Process meeting recordings:

transcribe(file_path="/path/to/meeting.mp3")
→ Full meeting transcript

Voice Responses

Generate spoken responses for channel messages:

speak(text="API status is healthy, 94 tests passing.")
→ Send audio file back via channel

ARM Linux Support

Tested and working on Oracle Cloud ARM VM (Ubuntu 24.04, aarch64):

ServiceRAM UsageModel
Whisper STT~190 MBggml-base (141 MB)
Kokoro TTS~1.2 GBkokoro-v1.0

Both services installed via VoiceMode's service manager which handles ARM-compatible builds automatically.

API Compatibility

This server connects to any service exposing OpenAI-compatible endpoints:

  • STT: POST /v1/audio/transcriptions (Whisper format)
  • TTS: POST /v1/audio/speech (OpenAI format)

This means you can also point it at:

  • OpenAI API (cloud, paid)
  • Groq Whisper API (cloud, cheap)
  • Any other OpenAI-compatible STT/TTS service

Just change WHISPER_URL / KOKORO_URL to your preferred endpoint.

License

MIT

Acknowledgments

Ver o original no GitHub

Bom para

Relacionados