Paxa Labs MCP

@paxalabs/mcp

Servidor oficial MCP para a API Paxa Labs: IA de fala em tailandês e inglês para seu agente, incluindo reprodução de áudio local.

Um agente conectado a este servidor pode falar em voz alta pelos alto-falantes da sua máquina, ler conteúdo longo em voz alta como uma fila de reprodução gerenciada, salvar fala em arquivos de áudio, traduzir qualquer idioma para tailandês e ler PDFs e imagens com OCR.

Beta. O conjunto de ferramentas está completo e testado de ponta a ponta, mas os nomes das ferramentas e o comportamento podem mudar antes da versão 1.0 conforme o feedback chega. Relate problemas em https://github.com/paxalabs/mcp/issues.

Início rápido

Você precisa de uma chave de API Paxa em paxalabs.com. Novas contas incluem créditos gratuitos.

Claude Code

claude mcp add paxa -e PAXA_API_KEY=pxa_your_key_here -- npx -y @paxalabs/mcp

Claude Desktop, Cursor e outros clientes MCP

Adicione à configuração MCP do seu cliente (para Claude Desktop: claude_desktop_config.json):

{
  "mcpServers": {
    "paxa": {
      "command": "npx",
      "args": ["-y", "@paxalabs/mcp"],
      "env": {
        "PAXA_API_KEY": "pxa_your_key_here"
      }
    }
  }
}

Um clique para Cursor ou VS Code: os botões instalam a mesma entrada em ~/.cursor/mcp.json ou nas configurações MCP do VS Code. Depois, substitua pxa_your_key_here na entrada paxa pela sua chave.

Ferramentas

Ferramenta	O que faz	Créditos
speak	Sintetiza uma linha curta e a reproduz pelos alto-falantes, bloqueando até terminar	15 por 1000 caracteres
queue_speech	Lê conteúdo longo em voz alta: divide automaticamente em partes, sintetiza antecipadamente enquanto reproduz, retorna imediatamente	15 por 1000 caracteres
control_playback	Controla a fila de áudio compartilhada: status, pause, resume, skip, clear	grátis
play_audio	Reproduz um arquivo de áudio local pelos alto-falantes	grátis
text_to_speech	Sintetiza fala em um arquivo de áudio (mp3, opus, wav) sem reproduzi-lo	15 por 1000 caracteres
translate_to_thai	Traduz qualquer idioma para tailandês, com controles de formalidade, glossário e contexto	25 por 1000 caracteres
ocr_document	OCR de PDF, PNG, JPEG ou WebP local para Markdown ou blocos estruturados	6,5 por página
list_voices	O elenco de vozes TTS com notas de personagem	grátis
list_models	Modelos disponíveis, limites e preços	grátis
get_account	Saldo de créditos, plano e limites de taxa	grátis

Todo o áudio flui por uma fila ordenada, então os sons nunca se sobrepõem: speak linhas entram na frente dos segmentos longos enfileirados, e queue_speech mantém um livro ou artigo fluindo sem lacunas, sintetizando o próximo segmento enquanto o atual é reproduzido.

Com um player compatível com streaming instalado (veja abaixo), a fala começa nos primeiros bytes da API em vez de após o download completo: cerca de 0,3 s até a primeira palavra, independentemente do comprimento, versus 0,7 s para uma linha curta e 2,5 s para um parágrafo longo quando armazenado em buffer.

Modo de voz para Claude Code

Três partes transformam o Claude Code em algo do qual você pode se afastar: ele fala quando tem novidades e chama você quando precisa de você.

1. Instale o servidor (Início rápido acima).

2. Diga ao Claude quando falar. Adicione isto a ~/.claude/CLAUDE.md, ou ao CLAUDE.md de um projeto:

## Voice

I have the Paxa MCP server (tools: speak, queue_speech, control_playback).
I am often away from the screen, so use voice like this:

- At the end of a turn where you did real work, call speak with a one or
  two sentence summary before writing the final message: what you did,
  what is next, and anything you need from me.
- When you need a decision from me, speak the question too.
- Keep it short and conversational. Never read code, file paths, logs, or
  long lists aloud. Those stay in text.
- Do not speak for quick back-and-forth or trivial answers.
- If I ask to hear something long, use queue_speech.
- Speak in the language I write in.

3. Seja avisado quando o Claude precisar de você. Quando o Claude Code espera por uma permissão ou uma resposta, o modelo não está em execução, então ele não pode chamar speak. O Claude Code dispara um hook nesses momentos, e paxa say transforma o hook em uma frase falada, como "Permissão necessária." Coloque o comando paxa no seu PATH:

npm install -g @paxalabs/mcp

Depois, adicione a ~/.claude/settings.json:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt|idle_prompt|agent_needs_input",
        "hooks": [{ "type": "command", "command": "paxa say" }]
      }
    ]
  }
}

paxa say pega a chave de PAXA_API_KEY, ou da entrada paxa em ~/.claude.json quando aquela não está definida, então o passo 1 é toda a configuração necessária. Um hook Stop configurado da mesma forma fala "Concluído." no final de cada turno.

As frases integradas são sintetizadas uma vez por voz e mantidas no diretório de cache do usuário (~/Library/Caches/paxa/say no macOS, ~/.cache/paxa/say no Linux, %LOCALAPPDATA%\paxa\cache\say no Windows). Após essa primeira reprodução, que custa bem menos de um crédito, uma notificação é reproduzida do disco: sem ida e volta à rede e sem créditos.

Para mudar as palavras, escreva seu próprio texto no comando do hook e adicione --cache para que ele receba o mesmo tratamento. Uma entrada por evento, já que o matcher seleciona o evento:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [{ "type": "command", "command": "paxa say --cache \"Hey, need your OK\"" }]
      },
      {
        "matcher": "idle_prompt|agent_needs_input",
        "hooks": [{ "type": "command", "command": "paxa say --cache --voice cookie \"Your turn\"" }]
      }
    ]
  }
}

Sem --cache, nada que você digitar ou canalizar para paxa say é gravado em disco, e mensagens transportadas dentro de um payload de hook nunca são.

No macOS, o afplay integrado precisa de cerca de meio segundo apenas para iniciar e parar, o que é a maior parte do atraso que você ouve em uma frase curta. Com brew install mpg123 (ou ffmpeg) instalado, frases em cache são reproduzidas por ele: mpg123 inicia em cerca de 50 ms, ffplay em cerca de 300 ms.

paxa say também funciona sozinho:

paxa say "Build finished"
paxa say --voice cookie "Deploy is live"

Se seu editor ou aplicativo de desktop não foi iniciado a partir de um terminal, seu PATH pode não incluir o diretório bin do node, e o hook falhará silenciosamente. Use o caminho absoluto para paxa no comando do hook se isso acontecer.

Variáveis de ambiente

Variável	Obrigatória	Padrão	Finalidade
PAXA_API_KEY	sim		Sua chave de API. O servidor inicia sem ela, mas toda ferramenta que chama a API falha com instruções de configuração que o agente pode repassar
PAXA_OUTPUT_DIR	não	diretório de trabalho	Onde text_to_speech salva arquivos
PAXA_DEFAULT_VOICE	não	nomyen	Voz usada quando uma chamada de ferramenta não escolhe uma. Texto em inglês geralmente soa melhor com uma voz em inglês (donut, cookie, toast, latte)
PAXA_BASE_URL	não	https://api.paxalabs.com	Substituição da origem da API

Suporte a reprodução

Plataforma	Player de arquivo	Player de streaming	Pausar/retomar
macOS	afplay (integrado)	ffplay, mpv ou mpg123 se instalado	sim
Linux	ffplay, mpv, mpg123, paplay ou aplay	ffplay, mpv ou mpg123	sim
Windows	ffplay se instalado, senão PowerShell (wav)	ffplay se instalado	não

Streaming precisa de um player que leia de stdin. No macOS, brew install ffmpeg (or mpv) o habilita; sem ele, a fala ainda é reproduzida por afplay após o download ser concluído. Se nenhum player for encontrado, as ferramentas de fala relatam isso claramente e text_to_speech ainda funciona.

Extensão Claude Desktop

Cada versão no GitHub inclui um pacote .mcpb. Baixe-o, abra-o com o Claude Desktop e insira sua chave de API nas configurações da extensão. O pacote carrega sua própria cópia do servidor e suas dependências, então funciona sem Node.js ou npm na máquina.

Desenvolvimento

pnpm install
pnpm build        # compile to dist/
pnpm typecheck
pnpm mcpb         # build release/paxalabs-mcp-<version>.mcpb for Claude Desktop

# live smoke test (spends a few credits, plays audio out loud)
PAXA_API_KEY=pxa_... TEST_OUT_DIR=/tmp/paxa-out node scripts/e2e.mjs