assemblyai-mcp

Un servidor MCP para la API de AssemblyAI. Transcripción, subtítulos, turnos de hablante, búsqueda de palabras y LeMUR, expuestos como herramientas que un agente puede llamar.

Escrito porque necesitaba uno y no había ninguno.

Instalación

npm install -g assemblyai-mcp

Claude Code:

claude mcp add assemblyai -e ASSEMBLYAI_API_KEY=your-key -- npx -y assemblyai-mcp

Cualquier otra cosa que hable MCP a través de stdio:

{
  "mcpServers": {
    "assemblyai": {
      "command": "npx",
      "args": ["-y", "assemblyai-mcp"],
      "env": { "ASSEMBLYAI_API_KEY": "your-key" }
    }
  }
}

Las claves se obtienen de el panel de control.

Herramientas

Tres decisiones que conviene conocer

transcribe espera. A un agente al que se le entrega un id de trabajo y un estado queued tiene que inventar un bucle de sondeo, y normalmente inventa uno malo: intervalo fijo, sin límite, sin mensaje cuando se rinde. Esperar es lo que quien llama pretendía. Pasa wait: false si de verdad quieres el id. En caso de tiempo de espera agotado, el error dice que la transcripción no se ha perdido y nombra la herramienta que la recuperará.

La salida larga tiene un límite y lo dice. Las transcripciones llegan a cientos de kilobytes. Una herramienta que devuelve todo eso gasta la ventana de contexto en texto que el agente va a resumir de todos modos. Todo lo que pueda ejecutarse durante mucho tiempo aplica un límite e informa de cuánto ha recortado, en lugar de truncar silenciosamente.

Los milisegundos se convierten en segundos. La API habla en milisegundos, lo cual es correcto para una API e incorrecto para un modelo que escribe una respuesta que una persona va a leer. Las marcas de tiempo salen como segundos con un decimal.

Desarrollo

npm install
npm run build
npm test

El cliente de la API (src/api.ts) no sabe nada de MCP y recibe un fetch inyectado, por lo que las pruebas se ejecutan contra un transporte simulado sin red ni clave. Las pruebas cubren lo que suele romperse en un envoltorio fino de API: que la clave nunca llegue a una URL, que los id se escapen para que un id hostil no pueda alterar la ruta, las respuestas que no son JSON (los subtítulos llegan como texto), los cuerpos de error que sacan a la luz la frase que escribió la API en lugar de un estado escueto, y que el bucle de sondeo se detenga tanto en completed como en error.

Nota para AssemblyAI

Si algo de esto te resulta útil, tómalo. Es MIT, y es tuyo para bifurcarlo, renombrarlo, absorberlo o desecharlo. Si prefieres tenerlo como servidor de primera parte, estaré encantado de ayudarte a que así sea.

MIT.