Speech MCP Server

Speech MCP Server

Um servidor Model Context Protocol que fornece capacidades de texto-para-fala usando o modelo TTS Kokoro.

Configuração

O servidor pode ser configurado usando as seguintes variáveis de ambiente:

Variável	Descrição	Padrão	Faixa Válida
MCP_DEFAULT_SPEECH_SPEED	Multiplicador de velocidade padrão para texto-para-fala	1.1	0.5 a 2.0
MCP_DEFAULT_VOICE	Voz padrão para texto-para-fala	af_bella	Qualquer ID de voz válido

No Cursor:

{
  "mcpServers": {
    "speech": {
      "command": "npx",
      "args": [
        "-y",
        "speech-mcp-server"
      ],
      "env": {
        "MCP_DEFAULT_SPEECH_SPEED": 1.3,
        "MCP_DEFAULT_VOICE": "af_bella"
      }
    }
  }
}

Recursos

• 🎯 Texto-para-fala de alta qualidade usando o modelo TTS Kokoro
• 🗣️ Múltiplas opções de voz disponíveis
• 🎛️ Parâmetros de fala personalizáveis (voz, velocidade)
• 🔌 Interface compatível com MCP
• 📦 Instalação e configuração fáceis
• 🚀 Nenhuma chave de API necessária

Instalação

# Using npm
npm install speech-mcp-server

# Using pnpm (recommended)
pnpm add speech-mcp-server

# Using yarn
yarn add speech-mcp-server

Uso

Execute o servidor:

# Using default configuration
npm start

# With custom configuration
MCP_DEFAULT_SPEECH_SPEED=1.5 MCP_DEFAULT_VOICE=af_bella npm start

O servidor fornece as seguintes ferramentas MCP:

• text_to_speech: Conversão básica de texto-para-fala
• text_to_speech_with_options: Texto-para-fala com velocidade personalizável
• list_voices: Lista todas as vozes disponíveis
• get_model_status: Verifica o status de inicialização do modelo TTS

Desenvolvimento

# Clone the repository
git clone <your-repo-url>
cd speech-mcp-server

# Install dependencies
pnpm install

# Start development server with auto-reload
pnpm dev

# Build the project
pnpm build

# Run linting
pnpm lint

# Format code
pnpm format

# Test with MCP Inspector
pnpm inspector

Ferramentas Disponíveis

1. text_to_speech

Converte texto em fala usando as configurações padrão.

{
  "type": "request",
  "id": "1",
  "method": "call_tool",
  "params": {
    "name": "text_to_speech",
    "arguments": {
      "text": "Hello world",
      "voice": "af_bella"  // optional
    }
  }
}

2. text_to_speech_with_options

Converte texto em fala com parâmetros personalizáveis.

{
  "type": "request",
  "id": "1",
  "method": "call_tool",
  "params": {
    "name": "text_to_speech_with_options",
    "arguments": {
      "text": "Hello world",
      "voice": "af_bella",  // optional
      "speed": 1.0,         // optional (0.5 to 2.0)
    }
  }
}

3. list_voices

Lista todas as vozes disponíveis para texto-para-fala.

{
  "type": "request",
  "id": "1",
  "method": "list_voices",
  "params": {}
}

4. get_model_status

Verifica o status atual da inicialização do modelo TTS. Isso é particularmente útil ao iniciar o servidor pela primeira vez, pois o modelo precisa ser baixado e inicializado.

{
  "type": "request",
  "id": "1",
  "method": "call_tool",
  "params": {
    "name": "get_model_status",
    "arguments": {}
  }
}

Exemplo de resposta:

{
  "content": [{
    "type": "text",
    "text": "Model status: initializing (5s elapsed)"
  }]
}

Valores de status possíveis:

• uninitialized: A inicialização do modelo não começou
• initializing: O modelo está sendo baixado e inicializado
• ready: O modelo está pronto para uso
• error: Ocorreu um erro durante a inicialização

Testes

Você pode testar o servidor usando o MCP Inspector ou enviando mensagens JSON brutas:

# List available tools
echo '{"type":"request","id":"1","method":"list_tools","params":{}}' | node dist/index.js

# List available voices
echo '{"type":"request","id":"2","method":"list_voices","params":{}}' | node dist/index.js

# Convert text to speech
echo '{"type":"request","id":"3","method":"call_tool","params":{"name":"text_to_speech","arguments":{"text":"Hello world","voice":"af_bella"}}}' | node dist/index.js

Integração com Claude Desktop

Para usar este servidor com o Claude Desktop, adicione o seguinte ao seu arquivo de configuração do Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "servers": {
    "speech": {
      "command": "npx",
      "args": ["@decodershq/speech-mcp-server"]
    }
  }
}

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.

Solução de Problemas

Problemas de Inicialização do Modelo

O servidor tenta automaticamente baixar e inicializar o modelo TTS na inicialização. Se você encontrar erros de inicialização:

1. O servidor tentará automaticamente novamente até 3 vezes com uma limpeza entre as tentativas
2. Use a ferramenta get_model_status para monitorar o progresso da inicialização e quaisquer erros
3. Se a inicialização falhar após todas as tentativas, tente remover manualmente os arquivos do modelo:

# Remove model files (MacOS/Linux)
rm -rf ~/.npm/_npx/**/node_modules/@huggingface/transformers/.cache/onnx-community/Kokoro-82M-v1.0-ONNX/onnx/model_quantized.onnx
rm -rf ~/.cache/huggingface/transformers/onnx-community/Kokoro-82M-v1.0-ONNX/onnx/model_quantized.onnx

# Then restart the server
npm start

A ferramenta get_model_status agora incluirá informações de nova tentativa em sua resposta:

{
  "content": [{
    "type": "text",
    "text": "Model status: initializing (5s elapsed, retry 1/3)"
  }]
}