Paxa Labs MCP

@paxalabs/mcp

Servidor oficial MCP para la API de Paxa Labs: IA de voz en tailandés e inglés para tu agente, incluida la reproducción de audio local.

Un agente conectado a este servidor puede hablar en voz alta a través de los altavoces de tu máquina, leer contenido largo en voz alta como una cola de reproducción gestionada, guardar voz en archivos de audio, traducir cualquier idioma al tailandés y leer PDFs e imágenes con OCR.

Beta. El conjunto de herramientas está completo y probado de extremo a extremo, pero los nombres de las herramientas y su comportamiento pueden cambiar antes de la versión 1.0 a medida que lleguen comentarios. Reporta problemas en https://github.com/paxalabs/mcp/issues.

Inicio rápido

Necesitas una clave de API de Paxa en paxalabs.com. Las cuentas nuevas incluyen créditos gratuitos.

Claude Code

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

Claude Desktop, Cursor y otros clientes MCP

Añade a la configuración MCP de tu cliente (para Claude Desktop: claude_desktop_config.json):

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

Un clic para Cursor o VS Code: los botones instalan la misma entrada en ~/.cursor/mcp.json o en la configuración MCP de VS Code. Luego reemplaza pxa_your_key_here en la entrada paxa con tu clave.

Herramientas

Herramienta	Qué hace	Créditos
speak	Sintetiza una línea corta y la reproduce por los altavoces, bloqueando hasta terminar	15 por cada 1000 caracteres
queue_speech	Lee contenido largo en voz alta: divide en fragmentos automáticamente, sintetiza por adelantado mientras reproduce, y regresa de inmediato	15 por cada 1000 caracteres
control_playback	Controla la cola de audio compartida: status, pause, resume, skip, clear	gratis
play_audio	Reproduce un archivo de audio local por los altavoces	gratis
text_to_speech	Sintetiza voz a un archivo de audio (mp3, opus, wav) sin reproducirlo	15 por cada 1000 caracteres
translate_to_thai	Traduce cualquier idioma al tailandés, con controles de formalidad, glosario y contexto	25 por cada 1000 caracteres
ocr_document	OCR de un PDF, PNG, JPEG o WebP local a Markdown o bloques estructurados	6.5 por página
list_voices	El catálogo de voces TTS con notas de personaje	gratis
list_models	Modelos disponibles, límites y precios	gratis
get_account	Saldo de créditos, plan y límites de tasa	gratis

Todo el audio fluye a través de una cola ordenada, por lo que los sonidos nunca se superponen: las líneas speak se deslizan por delante de los segmentos largos en cola, y queue_speech mantiene un libro o artículo fluyendo sin pausas al sintetizar el siguiente segmento mientras se reproduce el actual.

Con un reproductor compatible con streaming instalado (ver más abajo), el habla comienza con los primeros bytes de la API en lugar de después de la descarga completa: aproximadamente 0.3 s hasta la primera palabra sin importar la longitud, frente a 0.7 s para una línea corta y 2.5 s para un párrafo largo cuando se almacena en búfer.

Modo de voz para Claude Code

Tres piezas convierten a Claude Code en algo de lo que puedes alejarte: habla cuando tiene noticias y te llama cuando te necesita.

1. Instala el servidor (Inicio rápido arriba).

2. Dile a Claude cuándo hablar. Añade esto a ~/.claude/CLAUDE.md, o al CLAUDE.md de un proyecto:

## 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. Recibe aviso cuando Claude te necesita. Cuando Claude Code espera un permiso o una respuesta, el modelo no se está ejecutando, por lo que no puede llamar a speak. Claude Code dispara un hook en esos momentos en su lugar, y paxa say convierte el hook en una frase hablada como "Se necesita permiso." Pon el comando paxa en tu PATH:

npm install -g @paxalabs/mcp

Luego añade a ~/.claude/settings.json:

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

paxa say toma la clave de PAXA_API_KEY, o de la entrada paxa en ~/.claude.json cuando esa no está configurada, por lo que el paso 1 es toda la configuración que necesita. Un hook de Stop configurado de la misma manera dice "Listo." al final de cada turno.

Las frases integradas se sintetizan una vez por voz y se guardan en tu directorio de caché de usuario (~/Library/Caches/paxa/say en macOS, ~/.cache/paxa/say en Linux, %LOCALAPPDATA%\paxa\cache\say en Windows). Después de esa primera reproducción, que cuesta mucho menos de un crédito, una notificación se reproduce desde el disco: sin ida y vuelta de red y sin créditos.

Para cambiar las palabras, escribe tu propio texto en el comando del hook y añade --cache para que reciba el mismo tratamiento. Una entrada por evento, ya que el matcher selecciona el 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\"" }]
      }
    ]
  }
}

Sin --cache, nada de lo que escribas o canalices a paxa say se escribe en disco, y los mensajes transportados dentro de un payload de hook nunca se escriben.

En macOS, el afplay integrado necesita aproximadamente medio segundo solo para iniciar y detenerse, que es la mayor parte de la demora que escuchas en una frase corta. Con brew install mpg123 (o ffmpeg) instalado, las frases en caché se reproducen a través de ese: mpg123 inicia en unos 50 ms, ffplay en unos 300 ms.

paxa say también funciona por sí solo:

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

Si tu editor o aplicación de escritorio no se lanzó desde una terminal, su PATH puede no incluir tu directorio bin de node, y el hook fallará silenciosamente. Usa la ruta absoluta a paxa en el comando del hook si eso sucede.

Variables de entorno

Variable	Requerida	Predeterminado	Propósito
PAXA_API_KEY	sí		Tu clave de API. El servidor se inicia sin ella, pero cada herramienta que llama a la API falla entonces con instrucciones de configuración que el agente puede transmitir
PAXA_OUTPUT_DIR	no	directorio de trabajo	Dónde text_to_speech guarda archivos
PAXA_DEFAULT_VOICE	no	nomyen	Voz utilizada cuando una llamada de herramienta no elige una. El texto en inglés generalmente suena mejor con una voz en inglés (donut, cookie, toast, latte)
PAXA_BASE_URL	no	https://api.paxalabs.com	Anulación del origen de la API

Soporte de reproducción

Plataforma	Reproductor de archivos	Reproductor de streaming	Pausa/reanudar
macOS	afplay (integrado)	ffplay, mpv o mpg123 si están instalados	sí
Linux	ffplay, mpv, mpg123, paplay o aplay	ffplay, mpv o mpg123	sí
Windows	ffplay si está instalado, si no PowerShell (wav)	ffplay si está instalado	no

El streaming necesita un reproductor que lea desde stdin. En macOS, brew install ffmpeg (or mpv) lo habilita; sin él, el habla aún se reproduce a través de afplay después de que se complete la descarga. Si no se encuentra ningún reproductor, las herramientas de voz lo informan claramente y text_to_speech aún funciona.

Extensión de Claude Desktop

Cada versión en GitHub incluye un paquete .mcpb. Descárgalo, ábrelo con Claude Desktop e ingresa tu clave de API en la configuración de la extensión. El paquete lleva su propia copia del servidor y sus dependencias, por lo que funciona sin Node.js ni npm en la máquina.

Desarrollo

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