Typecast API

Um servidor MCP para a API Typecast, permitindo geração de voz com IA para diversos conteúdos.

GitHub
3
Experimente este MCPPatrocinado

Documentação

typecast-api-mcp-server

Servidor MCP para typecast-api, permitindo integração perfeita com clientes MCP. Este projeto fornece uma forma padronizada de interagir com a API Typecast por meio do Model Context Protocol.

Sobre

Este projeto implementa um servidor Model Context Protocol para a API Typecast, permitindo que clientes MCP interajam com a API Typecast de forma padronizada.

Modelos Suportados

ModeloDescriçãoControle de Emoção
ssfm-v30Modelo mais recente (recomendado)Predefinição + Modo Inteligente
ssfm-v21Modelo de produção estávelSomente predefinição

Recursos do ssfm-v30

  • 7 Predefinições de Emoção: normal, feliz, triste, bravo, sussurro, tom acima, tom abaixo
  • Modo Inteligente: A IA infere automaticamente a emoção a partir do contexto usando previous_text e next_text
  • 37 Idiomas: Suporte estendido a idiomas

Status de Implementação de Recursos

RecursoStatus
Gerenciamento de Voz
Documentação de Pesquisa✅
Obter Vozes (API V3)✅
Obter Vozes com filtro use_cases✅
Obter Voz (API V3)✅
Recomendar Vozes✅
Texto para Fala✅
Texto para Fala (Streaming)✅
Texto para Fala (com Timestamps)✅
Obter Minha Assinatura✅
Reproduzir Áudio✅
Controles de Saída
Normalização de volume target_lufs✅
Suporte ssfm-v30
Modo Predefinição✅
Modo Inteligente✅
Voz Personalizada
Clone Instantâneo / Profissional✅
Listar / Obter / Excluir Voz Personalizada✅

Clonagem Rápida de Voz

O servidor MCP expõe ferramentas para a API atual de Voz Personalizada:

  • clone_voice: cria uma voz personalizada com clone instantâneo a partir de um arquivo WAV ou MP3 local.
  • create_professional_voice: inicia um clone profissional; consulte o status antes de usar.
  • get_custom_voices e get_custom_voice: listam vozes ou verificam o status do clone.
  • delete_cloned_voice: exclui um ID de voz clonada que começa com uc_.

Restrições do clone instantâneo:

  • O nome da voz deve ter de 1 a 30 caracteres.
  • A amostra de áudio deve ser WAV ou MP3.
  • A amostra de áudio deve ter 25 MB ou menos.
  • Use ssfm-v30 a menos que você tenha um motivo específico de compatibilidade.

Fluxo típico:

  1. Execute clone_voice com name, audio_file_path e model opcional.
  2. Use o next_step_voice_id e o next_step_model retornados em text_to_speech, text_to_speech_stream ou text_to_speech_with_timestamps.
  3. Execute delete_cloned_voice quando a voz clonada temporária não for mais necessária.

A clonagem profissional retorna 202 Accepted. Consulte get_custom_voice até que o status se torne completed ou failed; a conclusão pode levar até duas horas.

Recomendações de Voz

Use recommend_voices quando você souber o estilo, o humor, o idioma ou o caso de uso desejado, mas ainda não souber o ID exato da voz. Ele chama GET /v1/voices/recommendations e retorna candidatos ordenados por pontuação.

A resposta de recomendação contém intencionalmente apenas voice_id, voice_name e score. Se um agente precisar de detalhes sobre uma voz recomendada, chame get_voice para cada ID retornado ou get_voices para uma lista filtrada mais ampla antes de usar o ID em TTS.

Configuração

Servidor Hospedado

O endpoint HTTP Streamable hospedado é:

https://typecast-api-docs-web-production.up.railway.app/mcp

Sem autenticação, o servidor expõe apenas search_documentation. Envie uma chave da API Typecast em cada solicitação MCP para desbloquear as ferramentas da API Typecast:

X-API-KEY: YOUR_TYPECAST_API_KEY

Authorization: Bearer YOUR_TYPECAST_API_KEY também é suportado. O servidor hospedado não armazena a chave. O áudio gerado é retornado como uma URL de download privada e impossível de adivinhar, que expira após uma hora. play_audio continua sendo uma ferramenta somente local, pois um servidor hospedado não pode reproduzir som no dispositivo do cliente MCP.

Para preservar a forma como o código de integração Typecast foi criado, os clientes hospedados podem enviar ambos os cabeçalhos de atribuição juntos:

X-Typecast-Integration-Source: api-docs
X-Typecast-Generated-By: codex

Use api-page para integração na página da API e api-docs para integração na documentação da API. Os valores legados llms e skill continuam aceitos. X-Typecast-Generated-By aceita um token ASCII minúsculo de até 32 caracteres. O servidor mantém seu próprio User-Agent typecast-mcp/<version> e anexa essa atribuição em vez de substituí-la.

No servidor hospedado, clone_voice aceita apenas audio_base64 juntamente com um audio_filename terminando em .wav ou .mp3. audio_file_path está disponível somente quando este servidor MCP é executado localmente.

Variáveis de Ambiente

Defina as seguintes variáveis de ambiente:

TYPECAST_API_KEY=<your-api-key>
TYPECAST_OUTPUT_DIR=<your-output-directory> # default: ~/Downloads/typecast_output
TYPECAST_INTEGRATION_SOURCE=<llms|skill|api-page|api-docs> # optional; set both attribution variables
TYPECAST_GENERATED_BY=<coding-agent-id>                     # optional; e.g. codex or claude-code

Uso com Claude Desktop / Cursor

Você pode adicionar o seguinte ao seu claude_desktop_config.json ou às configurações MCP do Cursor:

Recomendado: Usando uvx (Sem instalação necessária)

{
  "mcpServers": {
    "typecast-api-mcp-server": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/neosapience/typecast-api-mcp-server.git",
        "typecast-api-mcp-server"
      ],
      "env": {
        "TYPECAST_API_KEY": "YOUR_API_KEY",
        "TYPECAST_OUTPUT_DIR": "PATH/TO/YOUR/OUTPUT/DIR"
      }
    }
  }
}

Este método busca e executa automaticamente o servidor do GitHub sem clonagem manual.

Nota para usuários Linux: Se você estiver executando no Linux, precisará adicionar a variável de ambiente XDG_RUNTIME_DIR à seção env:

"env": {
  "TYPECAST_API_KEY": "YOUR_API_KEY",
  "TYPECAST_OUTPUT_DIR": "PATH/TO/YOUR/OUTPUT/DIR",
  "XDG_RUNTIME_DIR": "/run/user/1000"
}

Alternativa: Instalação Local

Se preferir clonar e executar localmente:

Git Clone

git clone https://github.com/neosapience/typecast-api-mcp-server.git
cd typecast-api-mcp-server

Dependências

Este projeto requer Python 3.10 ou superior e usa uv para gerenciamento de pacotes.

# Create virtual environment and install packages
uv venv
uv pip install -e .

Configuração Local

{
  "mcpServers": {
    "typecast-api-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/PATH/TO/YOUR/PROJECT",
        "run",
        "typecast-api-mcp-server"
      ],
      "env": {
        "TYPECAST_API_KEY": "YOUR_API_KEY",
        "TYPECAST_OUTPUT_DIR": "PATH/TO/YOUR/OUTPUT/DIR"
      }
    }
  }
}

Substitua /PATH/TO/YOUR/PROJECT pelo caminho real onde seu projeto está localizado.

Execução Manual

Você também pode executar o servidor manualmente:

uv run python app/main.py

Contribuindo

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

Licença

Licença MIT