Skip to main content
Glama

yeastar-mcp

CI CodeQL Licenza: MIT Python 3.11+ MCP 2026-07-28

Server MCP per amministrare un centralino Yeastar P-Series Software Edition da un assistente AI (Claude Code, Claude Desktop o altri client MCP). Gira dentro la LAN del centralino e usa la OpenAPI ufficiale del PBX (openapi/v1.0).

  • Lettura di tutto: interni, gruppi, trunk, rotte, IVR, ring group, code, orari, festività, rubriche, blacklist, telefoni, impostazioni globali, CDR, stato live di code e chiamate.

  • Modifica con un flusso in due fasi: anteprima → conferma. Nessuna modifica parte senza un sì esplicito.

  • Prima di ogni modifica il server salva uno snapshot. Dopo la modifica rilegge la configurazione e verifica che i valori siano stati applicati. Tutto finisce nel registro, e ogni modifica di configurazione si può annullare.

Stato: versione 0.1.0. È stata testata contro un PBX simulato che riproduce il formato della OpenAPI, non ancora contro un centralino reale. Prima di usarla in produzione provala su un'istanza di test o in finestra di manutenzione, e fai un backup (vedi sotto).


Come funziona una modifica

Utente: "cambia il nome dell'interno 2000 in Mario Rossi"
  │
  ├─ yeastar_search(extension, "2000")          → id 39
  ├─ yeastar_prepare_change(extension, update, 39, {caller_id_name: "Mario Rossi"})
  │     legge lo stato attuale, calcola il diff, NON tocca il PBX
  │     ← change_id chg_1a2b3c4d + anteprima (prima/dopo)
  │
Assistente: "Cambio caller_id_name da 'Leo Ball' a 'Mario Rossi'. Confermi?"
Utente: "sì"
  │
  └─ yeastar_apply_change(chg_1a2b3c4d, confirm=true)
        1. ricontrolla che nessuno abbia cambiato l'interno nel frattempo
        2. salva lo snapshot "prima" in data/snapshots/
        3. esegue la modifica
        4. rilegge l'interno e verifica il risultato
        5. scrive la riga nel registro data/audit.jsonl

Conferma diretta dell'utente (MCP elicitation)

Se il client supporta l'elicitation MCP, yeastar_apply_change non si fida solo dell'assistente. Il server mostra direttamente a te, nell'interfaccia del client, un modulo Sì/No con il riepilogo della modifica (segreti mascherati). L'assistente non può compilarlo al tuo posto. Se rispondi No o chiudi il modulo, la modifica viene annullata.

CONFIRM_MODE

Comportamento

auto (default)

Modulo di conferma se il client lo supporta, altrimenti conferma in chat

elicit

Modulo obbligatorio: con client che non lo supportano le modifiche sono rifiutate

chat

Solo conferma in chat, tramite l'assistente

Il registro annota per ogni modifica il canale di conferma (confermata_tramite).

Le anteprime scadono dopo 15 minuti (CHANGE_TTL_SECONDS) e si possono applicare una sola volta. yeastar_prepare_rollback(change_id) prepara l'annullamento: ripristina i valori precedenti, elimina l'oggetto creato oppure ricrea quello cancellato. Anche l'annullamento passa da anteprima e conferma.

Related MCP server: Veeam Backup & Replication MCP Server

Strumenti (tool) esposti

Tool

Cosa fa

Modifica il PBX?

yeastar_overview

Modello, firmware, capacità, stato del server

no

yeastar_catalog

Risorse e operazioni supportate

no

yeastar_list / yeastar_search / yeastar_get / yeastar_query

Lettura delle risorse

no

yeastar_read

Qualsiasi endpoint di sola lettura (CDR, queue/agent_status, call/query, system/get_menuoptions…)

no

yeastar_prepare_change

Anteprima di create/update/delete di una risorsa o di un'impostazione globale

no

yeastar_prepare_operation

Anteprima di un'operazione live (riavvio telefoni, pausa agenti, chiamate, conferenze)

no

yeastar_prepare_raw

Anteprima di una chiamata diretta a un endpoint fuori catalogo

no

yeastar_prepare_rollback

Anteprima dell'annullamento di una modifica applicata

no

yeastar_apply_change

Applica una modifica preparata (confirm=true)

sì

yeastar_cancel_change / yeastar_pending_changes

Gestione delle anteprime in attesa

no

yeastar_audit_log

Registro delle modifiche

no

Risorse (yeastar_catalog dà l'elenco completo):

  • interni: extension, extension_group, organization

  • routing: trunk, inbound_route, outbound_route, ivr, ring_group, queue, paging, conference, custom_prompt

  • orari: timezone, business_hour, holiday

  • rubriche: company_contact, phonebook, blocked_number, allowed_number, pin_list

  • telefoni e sistema: phone, backup, wakeup_call

  • impostazioni globali: feature_codes, auto_recording, ring_group_options, queue_options, queue_pause_reasons, preferences, prompt_preferences, web_server, extension_status_monitor, trunk_status_monitor, webhook, cdr_options

Operazioni live:

  • telefoni: phone_reboot, phone_reprovision, phone_batch_create/update/delete

  • agenti e code: agent_login, agent_pause, queue_agents_login, queue_agents_pause

  • conferenze: conference_*

  • chiamate: call_dial, call_hangup, call_transfer, call_hold…

  • varie: extension_send_welcome_email

Sicurezza

  • Bearer token obbligatorio in HTTP (MCP_AUTH_TOKEN, almeno 24 caratteri). Il confronto è a tempo costante. Senza token il server risponde 401.

  • Allowlist IP facoltativa (MCP_ALLOWED_IPS) e protezione da DNS rebinding (MCP_ALLOWED_HOSTS).

  • HTTPS diretto con MCP_TLS_CERT/MCP_TLS_KEY, oppure dietro un reverse proxy.

  • Bloccati di default:

    • endpoint che restituiscono password/PIN in chiaro (extension/getpassword, conference/viewpassword…), riattivabili con YEASTAR_ALLOW_SECRETS;

    • ascolto e registrazione di chiamate (call/listen, call/record_*), riattivabili con YEASTAR_ALLOW_CALL_MONITORING. Valuta prima i vincoli dell'art. 4 dello Statuto dei lavoratori e del GDPR;

    • gestione token e attivazione del PBX (sempre).

  • Mascheramento: password, PIN e token compaiono come *** nelle risposte all'assistente. Un valore *** inviato in una modifica viene rifiutato, così non si sovrascrive un PIN per sbaglio.

  • Modalità sola lettura con YEASTAR_READ_ONLY=true.

  • Log puliti: il token del PBX non viene scritto nei log, perché gli URL di httpx sono silenziati.

  • Un solo token condiviso, rinnovato automaticamente e revocato all'arresto: Yeastar ammette al massimo 8 token per applicazione.

  • Conferma anche nel client. Non mettere yeastar_apply_change tra i tool "sempre consentiti" del client. Così, oltre alla conferma in chat, il client ti chiede il permesso a ogni applicazione.

1. Preparare il centralino

  1. Sul portale del PBX vai in Integrations → API e attiva l'API.

  2. Annota Client ID e Client Secret.

  3. Tra gli IP consentiti per l'API aggiungi l'IP della macchina che farà girare questo server.

  4. Verifica che il firmware sia almeno 83.7.0.16 (consigliato l'ultimo disponibile).

2. Installazione con Docker (consigliata)

Su una VM o un host nella stessa LAN del centralino. Puoi usare l'immagine pubblicata a ogni release, ghcr.io/OWNER/yeastar-mcp:<versione> (amd64/arm64, con SBOM e attestazione), verificabile con gh attestation verify oci://ghcr.io/OWNER/yeastar-mcp:<versione> --owner OWNER. In alternativa costruiscila dal sorgente:

cp .env.example .env
# compila YEASTAR_BASE_URL, YEASTAR_CLIENT_ID, YEASTAR_CLIENT_SECRET, MCP_AUTH_TOKEN, MCP_ALLOWED_IPS
python3 -c "import secrets; print(secrets.token_urlsafe(32))"   # per MCP_AUTH_TOKEN

# in docker-compose.yml sostituisci 192.168.1.20 con l'IP LAN dell'host
docker compose up -d --build
docker compose logs -f
curl http://192.168.1.20:8765/healthz       # {"status":"ok"}

I dati persistenti (registro e snapshot) stanno in ./data.

Senza Docker

uv sync --no-dev                 # oppure: python3 -m venv .venv && . .venv/bin/activate && pip install .
set -a; . ./.env; set +a
uv run yeastar-mcp

Per un servizio permanente puoi usare un'unità systemd che esegue yeastar-mcp con EnvironmentFile=/percorso/.env.

3. Collegare il client

Il client deve stare in una rete che raggiunge il server (la LAN o una VPN). I connettori personalizzati di claude.ai sul web partono dal cloud e non vedono la tua LAN. Usa quindi uno dei client qui sotto.

Claude Code

claude mcp add --transport http yeastar http://192.168.1.20:8765/mcp \
  --header "Authorization: Bearer IL_TUO_TOKEN"

Claude Desktop, tramite il bridge mcp-remote (serve Node.js). In claude_desktop_config.json:

{
  "mcpServers": {
    "yeastar": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://192.168.1.20:8765/mcp",
               "--allow-http", "--header", "Authorization:${YEASTAR_MCP_AUTH}"],
      "env": { "YEASTAR_MCP_AUTH": "Bearer IL_TUO_TOKEN" }
    }
  }
}

Con HTTPS attivo usa https:// e togli --allow-http.

Uso locale senza rete (stdio, client e server sulla stessa macchina): imposta MCP_TRANSPORT=stdio e avvia yeastar-mcp come comando del client. In questa modalità il token non serve.

Esempi di richieste

  • "Mostrami tutti gli interni e quali telefoni sono offline"

  • "Che agenti sono in pausa nella coda 6400?" (usa yeastar_read queue/agent_status)

  • "Aggiungi il 24 dicembre pomeriggio alle festività"

  • "Cambia la destinazione fuori orario della rotta in ingresso 'Principale' sull'IVR 6200"

  • "Riavvia il telefono della reception"

  • "Fai un backup prima di procedere" (yeastar_prepare_change backup create)

  • "Annulla l'ultima modifica" (yeastar_audit_log, poi yeastar_prepare_rollback)

Note sull'API Yeastar

  • Ogni oggetto ha un id univoco diverso dal numero: l'interno 2000 può avere id 39. Il server lo trova con yeastar_search.

  • Gli update inviano solo i campi cambiati. I campi lista (per esempio outbound_route_permission o pause_reason_list) vengono sostituiti per intero: l'anteprima lo segnala con un avviso.

  • Se il PBX normalizza un valore (per esempio un'email in minuscolo), la verifica restituisce DA CONTROLLARE con i valori letti. Non è un errore, ma conviene darci un'occhiata.

  • Il rollback di una cancellazione ricrea l'oggetto con un nuovo id. I riferimenti in rotte, gruppi e code e le password di registrazione vanno ripristinati a mano.

  • La documentazione Yeastar usa sia extension_group/… sia extensiongroup/…: il server prova entrambi e ricorda quello che funziona.

  • I nomi dei parametri delle operazioni live seguono la Developer Guide Yeastar. yeastar_catalog riporta esempi e link.

File su disco

Percorso

Contenuto

data/audit.jsonl

Una riga JSON per ogni modifica (riuscita o rifiutata dal PBX), con i segreti mascherati

data/snapshots/<change_id>.json

Stato prima (e dopo) di ogni modifica. Permessi 600: può contenere PIN

Configurazione completa

Tutte le variabili, commentate, sono in .env.example.

Sviluppo

uv sync && uv run pre-commit install
uv run ruff format --check . && uv run ruff check . && uv run mypy && uv run pytest --cov

I test avviano un PBX simulato e il server MCP vero in HTTP, poi lo usano con un client MCP vero (sia con l'handshake classico sia con quello del protocollo 2026-07-28). Coprono:

  • autenticazione, allowlist IP, DNS rebinding, sola lettura;

  • mascheramento dei segreti, alias dei percorsi;

  • anteprima/conferma, conferma diretta via elicitation (sì, no, chiusura), deriva concorrente;

  • verifica post-modifica, rollback di update/create/delete;

  • errori del PBX, rinnovo e scadenza del token, blocco degli endpoint sensibili;

  • avvio da riga di comando.

Le regole del progetto sono in CONTRIBUTING.md. Le segnalazioni di sicurezza vanno fatte come indicato in SECURITY.md, che contiene anche il modello di minaccia.

Roadmap

  • Test su centralini reali (firmware 83.2x) e catalogo dei parametri delle operazioni live

  • OAuth 2.1 (spec MCP authorization) per avere più amministratori con identità e permessi distinti

  • Anteprime legate alla sessione/utente che le ha preparate

  • Eventi Yeastar (webhook/WebSocket) esposti come notifiche MCP

  • Interfaccia e messaggi in inglese

Crediti

Sviluppato da NextGen Technologies Italia (Next Gen Technologies Italia SRLS, Prato), che si occupa di reti aziendali, AI e infrastrutture. Per installazione e assistenza: prenota una call.

Progetto indipendente, non affiliato a Yeastar. "Yeastar" e "P-Series" sono marchi dei rispettivi proprietari.

Rilasciato con licenza MIT.

Available Tools

15 tools
yeastar_apply_changeA
Destructive

APPLICA al centralino una modifica preparata. Da chiamare SOLO dopo che l'utente ha visto l'anteprima e ha risposto esplicitamente di sì. Se il client lo supporta, il server chiede anche una conferma diretta all'utente (modulo Sì/No) che l'assistente non può compilare al posto suo. Controlla che la configurazione non sia cambiata, salva uno snapshot, esegue, rilegge e verifica, scrive nel registro.

Inputs: confirm (required), change_id (required). Returns: object

yeastar_audit_logB
Read-onlyIdempotent

Registro delle modifiche applicate (o fallite) tramite questo server, dalla più recente.

Inputs: limit, change_id. Returns: object

yeastar_cancel_changeB
Read-only

Scarta una modifica preparata e non ancora applicata.

Inputs: change_id (required). Returns: object

yeastar_catalogA
Read-onlyIdempotent

Elenco delle risorse configurabili (con i verbi disponibili) e delle operazioni live (riavvio telefoni, pausa agenti, chiamate, conferenze) supportate da questo server.

Inputs: no named parameters. Returns: object

yeastar_getB
Read-onlyIdempotent

Configurazione completa di un oggetto (o di un'impostazione globale).

Inputs: resource (required), id. Returns: object

yeastar_listA
Read-onlyIdempotent

Elenca gli oggetti di una risorsa (paginato). Restituisce i dati base; per il dettaglio usa yeastar_get.

Inputs: resource (required), page, filters, sort_by, +2 more. Returns: object

yeastar_overviewA
Read-onlyIdempotent

Informazioni generali sul centralino: modello, versione firmware, capacità (interni, chiamate contemporanee) e stato del server MCP. Usalo come primo controllo della connessione.

Inputs: no named parameters. Returns: object

yeastar_pending_changesA
Read-onlyIdempotent

Elenca le modifiche preparate in attesa di conferma (scadono dopo CHANGE_TTL_SECONDS).

Inputs: no named parameters. Returns: object

yeastar_prepare_changeA
Read-only

PREPARA (non applica) una modifica di configurazione. Legge lo stato attuale, calcola il diff prima/dopo e restituisce un change_id. Mostra l'anteprima all'utente e aspetta il suo sì prima di chiamare yeastar_apply_change.

Inputs: action (required), resource (required), id, data. Returns: object

yeastar_prepare_operationA
Read-only

PREPARA (non esegue) un'operazione live: riavvio/riprovisioning/modifica batch dei telefoni, login/pausa agenti, gestione conferenze, controllo chiamate. Restituisce un change_id da confermare.

Inputs: operation (required), args. Returns: object

yeastar_prepare_rawA
Read-only

PREPARA una chiamata diretta a un endpoint non coperto dal catalogo (escape hatch). Nessun diff automatico: usa solo se le altre funzioni non bastano. Va confermata con yeastar_apply_change.

Inputs: method (required), endpoint (required), body, params. Returns: object

yeastar_prepare_rollbackA
Read-only

PREPARA l'annullamento di una modifica già applicata, usando lo snapshot salvato: ripristina i valori precedenti (update), elimina l'oggetto creato (create) o lo ricrea (delete).

Inputs: change_id (required). Returns: object

yeastar_queryC
Read-onlyIdempotent

Configurazione completa di più oggetti in una sola chiamata.

Inputs: ids (required), resource (required). Returns: object

yeastar_readA
Read-onlyIdempotent

Chiama qualsiasi endpoint di SOLA LETTURA dell'API Yeastar (GET). Utile per CDR, report, stato live di code/chiamate/conferenze, registrazioni, log, opzioni dei menu. Rifiuta gli endpoint che modificano qualcosa: per quelli usa yeastar_prepare_raw.

Inputs: endpoint (required), params. Returns: object

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 15 tools

    Disambiguation4/5

    Most tools have clearly distinct roles: list/search/get/query separate basic listing, lookup, single-detail, and batch-detail reads, while prepare_change, prepare_operation, prepare_raw, and prepare_rollback are differentiated by config changes, live operations, raw escape hatch, and rollback. Some overlap remains between yeastar_read and the catalog-based read tools, since read can also retrieve status/report data that overlaps conceptually with get/query/list.

    Naming Consistency4/5

    All tools use a consistent yeastar_ snake_case prefix, and the core workflow names (prepare_change, apply_change, cancel_change, pending_changes, audit_log) are highly predictable. Minor inconsistency comes from mixing verb-style names (list, search, get, query, read) with noun-style names (overview, catalog, audit_log), though the pattern remains readable.

    Tool Count5/5

    Fifteen tools is at the upper end of the ideal range but appropriate for a PBX management server that separates read operations, safe preparation, application, cancellation, rollback, and auditing. Each tool appears to serve a distinct part of the configuration/live-operation lifecycle rather than duplicating another.

    Completeness5/5

    The server covers discovery (overview, catalog), read workflows (list, search, get, query, read), safe write workflows (prepare/apply/cancel/pending), rollback, raw endpoint escape, and audit logging. This provides broad CRUD/lifecycle coverage for PBX configuration and live operations with no obvious dead ends, especially because generic read and raw/prepare paths cover uncatalogued endpoints.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to interact with Veeam Backup & Replication infrastructure through natural language, allowing monitoring, management, and troubleshooting of backup jobs, sessions, and restore points.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      This MCP server enables AI assistants to read PBX state—extensions, DID numbers, SIP trunk providers, tenants, and live statistics—from ICTPBX via the ICTCore REST API, without placing calls or changing configuration.
      5
      62 npm
      16
      MIT