Skip to main content
Glama
Sign In
centralita-vpbx-mcp

centralita-vpbx-mcp

by DerechoVirtual
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

centralita-vpbx-mcp

MCP (Model Context Protocol) para la centralita virtual vpbx.me (plataforma de PBX en la nube basada en Java/JAX-RS sobre FreeSWITCH). Da a un asistente compatible con MCP (Claude Code, Claude Desktop, etc.) acceso a la telefonía: historial, grabaciones, llamadas en tiempo real, click-to-call, control de llamadas, extensiones, colas, agentes, contactos y buzones.

Arquitectura TypeScript/Node sobre el SDK oficial de MCP. La API está documentada en API_REFERENCE.md.

⚠️ Proyecto comunitario, no oficial de la plataforma. Úsalo solo con centralitas para las que tengas autorización.

Qué puede hacer (52 herramientas)

🟢 Solo lectura (siempre disponibles)

  • Tiempo real: pbx_live_status (llamadas en curso + estado de extensiones).

  • Historial (CDR): pbx_list_calls, pbx_get_call, pbx_count_calls.

  • Grabaciones: pbx_get_recording_url, pbx_download_recording (guarda el MP3 a disco), pbx_download_voicemail_audio.

  • Extensiones: pbx_list_extensions, pbx_get_extension, pbx_find_extension_by_username.

  • Colas: pbx_list_queues, pbx_get_queue, pbx_queue_callers, pbx_queue_state, pbx_queue_waittime.

  • Agentes: pbx_list_agents, pbx_get_agent, pbx_agent_breaktypes, pbx_agent_status, pbx_agent_statuscount.

  • Contactos: pbx_list_contacts, pbx_get_contact.

  • Locuciones / buzones: pbx_list_announcements, pbx_get_announcement, pbx_list_voicemails, pbx_get_voicemail.

  • Encuestas: pbx_list_surveys.

🔵 Atajos / informes (solo lectura, alto valor)

  • pbx_calls_in_range — todas las llamadas de un día/rango (pagina solo y deduplica) + resumen.

  • pbx_calls_report — informe por extensión: salientes/entrantes/atendidas/minutos, resolviendo el número de extensión a su nombre.

  • pbx_extension_directory — directorio número → nombre → email.

  • pbx_recordings_in_range — llamadas grabadas de un periodo, listas para descargar y transcribir.

🟠 Acciones de llamada — candado CENTRALITA_ENABLE_CALLS

pbx_originate_call, pbx_click_to_call_external, pbx_click_to_call_queue, pbx_click_to_call_inverse_queue, pbx_hangup, pbx_schedule_hangup, pbx_blind_transfer, pbx_attended_transfer_start/complete/cancel, pbx_start_recording, pbx_stop_recording, pbx_broadcast_audio.

🔴 Escritura de configuración — candado CENTRALITA_ENABLE_WRITES

pbx_update_extension, pbx_reset_sip_password, pbx_update_contact, pbx_set_agent_status, pbx_update_cdr_vars, pbx_mark_voicemail_read/unread, pbx_delete_voicemail.

Related MCP server: 3CX MCP Server

Seguridad por capas

Tres candados independientes, todos OFF por defecto (arranca en solo lectura):

Variable

Por defecto

Desbloquea

CENTRALITA_ENABLE_CALLS

false

Originar/colgar/transferir/grabar llamadas reales

CENTRALITA_ENABLE_WRITES

false

Editar extensiones/contactos/agentes, borrar buzones…

CENTRALITA_ALLOW_SECRETS

false

Devolver contraseñas SIP/web en claro (si no, se redactan)

Las tools llevan anotaciones MCP (readOnlyHint / destructiveHint) para que el cliente agrupe lectura vs. acciones en su panel de permisos.

Nota: GET /api/extension de la plataforma puede devolver contraseñas SIP en claro. Este MCP las redacta por defecto. Trata tu CENTRALITA_API_KEY como un secreto sensible.

Instalación

git clone <este-repo> centralita-vpbx-mcp
cd centralita-vpbx-mcp
npm install
npm run build

Copia .env.example a .env y pon tu CENTRALITA_API_KEY.

Uso

Local (Claude Code / Claude Desktop · stdio)

npm start              # solo lectura

Registro en claude_desktop_config.json (o .mcp.json de Claude Code):

{
  "mcpServers": {
    "centralita": {
      "command": "node",
      "args": ["/ruta/a/centralita-vpbx-mcp/dist/index.js"],
      "env": {
        "CENTRALITA_API_KEY": "TU_API_KEY",
        "CENTRALITA_ENABLE_CALLS": "false",
        "CENTRALITA_ENABLE_WRITES": "false"
      }
    }
  }
}

Para permitir click-to-call, pon CENTRALITA_ENABLE_CALLS a "true".

Remoto (HTTP)

npm run start:http     # escucha en http://0.0.0.0:8788/mcp

Protégelo con CENTRALITA_MCP_AUTH_TOKEN (cabecera Authorization: Bearer <token>) y ponlo tras HTTPS. Endpoint de salud: GET /health.

Validación

node test-mcp.mjs

Comprueba el handshake MCP, lista las 52 tools, hace una lectura real (pbx_count_calls) y verifica que el candado de acciones bloquea pbx_hangup.

Arquitectura

src/
  config.ts        Carga .env + candados de seguridad
  client.ts        Cliente HTTP (X-Api-Key) + descarga binaria
  util.ts          jsonResult, ensureCalls/ensureWrites, fechas, redacción de secretos
  server.ts        Monta el McpServer y registra los 4 módulos
  index.ts         Arranque stdio (local) o HTTP (remoto)
  tools/
    read.ts        Lectura (CDR, grabaciones, extensiones, colas, agentes, contactos, buzones)
    workflow.ts    Atajos/informes (paginado de CDR, informe por extensión, directorio)
    actions.ts     Acciones de llamada (candado CENTRALITA_ENABLE_CALLS)
    write.ts       Escritura de configuración (candado CENTRALITA_ENABLE_WRITES)

Licencia

MIT — ver LICENSE.

Available Tools

52 tools
pbx_agent_breaktypesTipos de pausa de agenteA
Read-only

Catálogo de tipos de pausa/descanso de agentes.

Inputs: no named parameters.

pbx_agent_statusCambios de estado de agentesA
Read-only

Histórico/listado de cambios de estado de agentes.

Inputs: no named parameters.

pbx_agent_statuscountConteo de estados de agentesC
Read-only

Conteo agregado de cambios de estado de agentes.

Inputs: no named parameters.

pbx_attended_transfer_cancelTransferencia atendida — cancelarA

Cancela una transferencia atendida en curso y recupera la llamada original.

Inputs: callId (required).

pbx_attended_transfer_completeTransferencia atendida — completarA

Completa la transferencia atendida iniciada previamente (une las dos partes y sale).

Inputs: callId (required).

pbx_attended_transfer_startTransferencia atendida — iniciarA

Inicia una transferencia con consulta: pone la llamada en espera y marca a 'destination' para hablar antes de completar. ⚠️ Llamada real.

Inputs: callId (required), destination (required).

pbx_blind_transferTransferencia ciegaA
Destructive

Transfiere la llamada en curso a 'destination' sin consulta previa. ⚠️ Desvía una llamada real.

Inputs: callId (required), destination (required).

pbx_broadcast_audioReproducir una locución en una llamadaA

Inyecta/reproduce una locución (announcementId) dentro de la llamada en curso. ⚠️ Audio en una llamada real.

Inputs: callId (required), announcementId (required).

pbx_calls_in_rangeLlamadas de un periodo (paginado automático)A
Read-only

Recupera TODAS las llamadas de un día o rango recorriendo la paginación del CDR (tope 50/petición) y deduplicando. Devuelve la lista completa y un resumen: total, por tipo (entrante/saliente/interna), atendidas vs no atendidas y por causa de cuelgue.

Inputs: to, date, from, desde, +2 more.

pbx_calls_reportInforme de llamadas por trabajadorA
Read-only

Productividad telefónica por extensión en un día/rango: llamadas salientes hechas (y cuántas con respuesta), entrantes atendidas y minutos en línea. Resuelve el número de extensión a nombre del trabajador.

Inputs: to, date, from, desde, +1 more.

pbx_click_to_call_externalClick-to-call externo (dos números)A

Conecta dos números cualesquiera 'from' y 'to' a través de la centralita (callback). ⚠️ Hace sonar teléfonos reales.

Inputs: to (required), from (required), timeout, outboundId, +2 more.

pbx_click_to_call_inverse_queueClick-to-call inverso de colaC

Variante inversa: marca a 'to' en nombre de la cola. ⚠️ Llamada real.

Inputs: to (required), queueNumber (required), outboundId, forcedCallerIdNumber.

pbx_click_to_call_queueClick-to-call hacia una colaB

Llama a 'to' y, al contestar, lo encola en la cola indicada. ⚠️ Llamada real.

Inputs: to (required), queueNumber (required), outboundId, maxWaitingCallers, +1 more.

pbx_count_callsContar llamadas (CDR)A
Read-only

Número total de llamadas registradas (opcionalmente dentro de un rango).

Inputs: to, date, from, desde, +1 more.

pbx_delete_voicemailBorrar mensaje de vozB
DestructiveIdempotent

Elimina un mensaje de voz del buzón de una extensión. ⚠️ Acción irreversible.

Inputs: extensionId (required), voicemailId (required).

pbx_download_recordingDescargar grabación a discoA
Read-only

Descarga el MP3 de la grabación de una llamada y lo guarda en la carpeta de grabaciones del servidor (CENTRALITA_RECORDINGS_DIR). Devuelve la ruta local del archivo, lista para transcribir.

Inputs: callId (required), filename.

pbx_download_voicemail_audioDescargar audio de buzón a discoC
Read-only

Descarga el audio de un mensaje de voz y lo guarda en la carpeta de grabaciones. Devuelve la ruta local.

Inputs: extensionId (required), voicemailId (required), filename.

pbx_extension_directoryDirectorio de extensionesA
Read-only

Listado compacto número → nombre → email → id de cada extensión, para resolver quién es quién. Sin contraseñas.

Inputs: no named parameters.

pbx_find_extension_by_usernameBuscar extensión por númeroA
Read-only

Devuelve el id interno de una extensión a partir de su número/username (ej. '1003').

Inputs: username (required).

pbx_get_agentVer agenteC
Read-only

Detalle de un agente por su id.

Inputs: id (required).

pbx_get_announcementVer locuciónB
Read-only

Detalle de una locución por su id. El audio base64 se omite salvo includeAudio=true.

Inputs: id (required), includeAudio.

pbx_get_callVer una llamada (CDR)B
Read-only

Detalle de una llamada concreta por su callId (uuid).

Inputs: callId (required).

pbx_get_contactVer contacto por númeroA
Read-only

Busca un contacto de la agenda por su número de teléfono.

Inputs: number (required).

pbx_get_extensionVer extensiónA
Read-only

Ficha de una extensión por su id interno (no el número). Contraseñas redactadas salvo CENTRALITA_ALLOW_SECRETS=true.

Inputs: extensionId (required).

pbx_get_queueVer colaB
Read-only

Detalle de una cola por su id.

Inputs: queueId (required).

pbx_get_recording_urlURL de la grabaciónA
Read-only

Devuelve la URL directa de descarga (audio/mpeg) de la grabación de una llamada. Requiere cabecera X-Api-Key para descargarla. Para guardarla en disco usa 'pbx_download_recording'.

Inputs: callId (required).

pbx_get_voicemailVer mensaje de vozC
Read-only

Detalle de un mensaje de voz concreto.

Inputs: extensionId (required), voicemailId (required).

pbx_hangupColgar una llamada en cursoA
Destructive

Cuelga la llamada activa indicada por su callId/uuid (lo da pbx_live_status). ⚠️ Corta una llamada real.

Inputs: callId (required).

pbx_list_agentsListar agentesC
Read-only

Agentes del call center.

Inputs: no named parameters.

pbx_list_announcementsListar locucionesA
Read-only

Locuciones/anuncios (IVR, etc.). El audio en base64 se omite por defecto para no saturar; pásalo con includeAudio=true.

Inputs: includeAudio.

pbx_list_callsListar llamadas (CDR)A
Read-only

Registro de llamadas (Call Detail Records). Devuelve como máximo 50 por petición, las más recientes primero, dentro del rango. Para recorrer un día/periodo entero usa 'pbx_calls_in_range', que pagina solo.

Inputs: to, date, from, desde, +1 more.

pbx_list_contactsListar contactos (agenda)A
Read-only

Agenda de la centralita (nombre, número, marcación rápida). Filtra por subcadena de nombre con 'q' y limita con 'limit'.

Inputs: q, limit.

pbx_list_extensionsListar extensionesA
Read-only

Lista de extensiones (usuarios SIP) con su número, nombre, email, dominio y estado. Las contraseñas SIP/web se redactan salvo que el servidor arranque con CENTRALITA_ALLOW_SECRETS=true.

Inputs: no named parameters.

pbx_list_queuesListar colasC
Read-only

Colas de llamadas configuradas.

Inputs: no named parameters.

pbx_list_surveysListar encuestasC
Read-only

Encuestas de satisfacción configuradas.

Inputs: no named parameters.

pbx_list_voicemailsListar buzones de voz de una extensiónA
Read-only

Mensajes de voz de una extensión (por su id interno).

Inputs: extensionId (required).

pbx_live_statusLlamadas en curso (tiempo real)A
Read-only

Estado en vivo de la centralita: extensiones ocupadas/libres y las llamadas activas ahora mismo (uuid, quién llama, destino, estado). El uuid sirve como callId para colgar/transferir/grabar.

Inputs: no named parameters.

pbx_mark_voicemail_readMarcar buzón como leídoB
Destructive

Marca un mensaje de voz como escuchado/leído.

Inputs: extensionId (required), voicemailId (required).

pbx_mark_voicemail_unreadMarcar buzón como no leídoC
Destructive

Marca un mensaje de voz como no escuchado.

Inputs: extensionId (required), voicemailId (required).

pbx_originate_callOriginar llamada (click-to-call interno)A

Lanza una llamada: primero hace sonar la extensión 'from' y, cuando descuelga, marca a 'to'. Es el click-to-call clásico para que un trabajador llame a un número. ⚠️ Hace sonar teléfonos reales.

Inputs: to (required), from (required), timeout, autoAnswer, +2 more.

pbx_queue_callersLlamadas en espera en colasA
Read-only

Personas esperando en cola ahora mismo. Sin queueId devuelve todas las colas; con queueId, solo esa.

Inputs: queueId.

pbx_queue_stateEstado de una colaC
Read-only

Estado en vivo de una cola por su número.

Inputs: queueNumber (required).

pbx_queue_waittimeTiempo de espera de una colaA
Read-only

Tiempo de espera estimado/actual de una cola por su número.

Inputs: queueNumber (required).

pbx_recordings_in_rangeGrabaciones de un periodoA
Read-only

Lista las llamadas con grabación (recording=true) de un día/rango, con su metadato y la URL de descarga del MP3. Punto de partida para descargar y transcribir. No descarga nada por sí mismo.

Inputs: to, date, from, desde, +1 more.

pbx_reset_sip_passwordResetear contraseña SIP de una extensiónA
Destructive

Genera una nueva contraseña SIP para la extensión. ⚠️ El teléfono/softphone dejará de registrarse hasta reconfigurarlo con la nueva clave.

Inputs: extensionId (required).

pbx_schedule_hangupProgramar cuelgue de una llamadaB
Destructive

Cuelga la llamada indicada dentro de N segundos. ⚠️ Cortará una llamada real.

Inputs: callId (required), seconds (required).

pbx_set_agent_statusCambiar estado de un agenteB
Destructive

Cambia el estado de un agente (login/logout/pausa…). 'newStatus' es el código de estado de la plataforma.

Inputs: id (required), newStatus (required).

pbx_start_recordingEmpezar a grabar una llamada en cursoA

Activa la grabación de la llamada activa indicada. Aviso legal: graba a personas reales; asegúrate del consentimiento/aviso.

Inputs: callId (required).

pbx_stop_recordingParar de grabar una llamada en cursoC

Detiene la grabación de la llamada activa indicada.

Inputs: callId (required).

pbx_update_cdr_varsActualizar variables de una llamada (CDR)A
Destructive

Escribe variables/etiquetas (var1…var5 u otras) sobre el registro de una llamada. Útil para clasificar llamadas (cliente, motivo, expediente…).

Inputs: vars (required), callId (required).

pbx_update_contactCrear/editar contacto de la agendaC
Destructive

Da de alta o actualiza un contacto de la agenda de la centralita (nombre, número, marcación rápida).

Inputs: name (required), number (required), speedDial.

pbx_update_extensionEditar extensiónA
Destructive

Modifica campos de una extensión (ej. name, email, dnd, cw…). Pasa solo los campos a cambiar en 'fields'. Consulta primero la ficha con pbx_get_extension.

Inputs: fields (required), extensionId (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    B3.2/5.0

    Scored across 52 tools

    Disambiguation4/5

    Most tools have clear, distinct purposes (e.g., originate_call vs click_to_call_external), but several call initiation and transfer tools are quite similar and could confuse an agent without careful reading of descriptions.

    Naming Consistency5/5

    All tools follow a consistent 'pbx_verb_noun' pattern, with descriptive names like pbx_list_extensions, pbx_get_call, pbx_hangup. Naming is uniform and predictable.

    Tool Count3/5

    52 tools is high, potentially overwhelming for an agent. However, they are organized by function (calls, queues, agents, etc.) and serve a complex domain, so it is borderline appropriate.

    Completeness3/5

    The set covers core PBX operations (calls, queues, agents, voicemails, etc.) well, but lacks management tools for queues, announcements, and surveys (only list/get available). Notable gaps in CRUD lifecycle.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • 3CX MCP Server

      SSIG-IT
      A
      license
      A
      quality
      C
      maintenance
      An MCP server that connects Claude to a 3CX Phone System (V20+), enabling user management, call monitoring, contact search, and forwarding configuration.
      22
      1
      MIT
    • VoIPbin MCP Server

      VoIPbin MCP Serverofficial

      voipbin
      A
      license
      B
      quality
      B
      maintenance
      An MCP server that enables AI assistants to interact with the VoIPbin CPaaS platform, exposing tools for managing calls, flows, messaging, conferencing, and more.
      66
      1
      MIT

    • five9-mcp

      outboundani
      A
      license
      Not graded
      quality
      B
      maintenance
      MCP server that connects AI assistants to Five9 contact center, allowing management of campaigns, agents, lists, and statistics via natural language commands.
      18
      MIT