yeastar-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@yeastar-mcp change the caller ID name of extension 2000 to Mario Rossi"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
yeastar-mcp
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.jsonlConferma 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.
| Comportamento |
| Modulo di conferma se il client lo supporta, altrimenti conferma in chat |
| Modulo obbligatorio: con client che non lo supportano le modifiche sono rifiutate |
| 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? |
| Modello, firmware, capacità, stato del server | no |
| Risorse e operazioni supportate | no |
| Lettura delle risorse | no |
| Qualsiasi endpoint di sola lettura (CDR, | no |
| Anteprima di create/update/delete di una risorsa o di un'impostazione globale | no |
| Anteprima di un'operazione live (riavvio telefoni, pausa agenti, chiamate, conferenze) | no |
| Anteprima di una chiamata diretta a un endpoint fuori catalogo | no |
| Anteprima dell'annullamento di una modifica applicata | no |
| Applica una modifica preparata ( | sì |
| Gestione delle anteprime in attesa | no |
| Registro delle modifiche | no |
Risorse (yeastar_catalog dà l'elenco completo):
interni:
extension,extension_group,organizationrouting:
trunk,inbound_route,outbound_route,ivr,ring_group,queue,paging,conference,custom_promptorari:
timezone,business_hour,holidayrubriche:
company_contact,phonebook,blocked_number,allowed_number,pin_listtelefoni e sistema:
phone,backup,wakeup_callimpostazioni 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/deleteagenti e code:
agent_login,agent_pause,queue_agents_login,queue_agents_pauseconferenze:
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 conYEASTAR_ALLOW_SECRETS;ascolto e registrazione di chiamate (
call/listen,call/record_*), riattivabili conYEASTAR_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_changetra 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
Sul portale del PBX vai in Integrations → API e attiva l'API.
Annota Client ID e Client Secret.
Tra gli IP consentiti per l'API aggiungi l'IP della macchina che farà girare questo server.
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-mcpPer 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, poiyeastar_prepare_rollback)
Note sull'API Yeastar
Ogni oggetto ha un
idunivoco diverso dal numero: l'interno 2000 può avere id 39. Il server lo trova conyeastar_search.Gli update inviano solo i campi cambiati. I campi lista (per esempio
outbound_route_permissionopause_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 CONTROLLAREcon 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/…siaextensiongroup/…: il server prova entrambi e ricorda quello che funziona.I nomi dei parametri delle operazioni live seguono la Developer Guide Yeastar.
yeastar_catalogriporta esempi e link.
File su disco
Percorso | Contenuto |
| Una riga JSON per ogni modifica (riuscita o rifiutata dal PBX), con i segreti mascherati |
| 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 --covI 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 toolsyeastar_apply_changeADestructive
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_logBRead-onlyIdempotent
Registro delle modifiche applicate (o fallite) tramite questo server, dalla più recente.
Inputs: limit, change_id. Returns: object
yeastar_cancel_changeBRead-only
Scarta una modifica preparata e non ancora applicata.
Inputs: change_id (required). Returns: object
yeastar_catalogARead-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_getBRead-onlyIdempotent
Configurazione completa di un oggetto (o di un'impostazione globale).
Inputs: resource (required), id. Returns: object
yeastar_listARead-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_overviewARead-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_changesARead-onlyIdempotent
Elenca le modifiche preparate in attesa di conferma (scadono dopo CHANGE_TTL_SECONDS).
Inputs: no named parameters. Returns: object
yeastar_prepare_changeARead-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_operationARead-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_rawARead-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_rollbackARead-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_queryCRead-onlyIdempotent
Configurazione completa di più oggetti in una sola chiamata.
Inputs: ids (required), resource (required). Returns: object
yeastar_readARead-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
yeastar_searchARead-onlyIdempotent
Cerca oggetti per numero o nome. Serve anche a trovare l'id da usare in get/update/delete.
Inputs: resource (required), search_value (required), page, filters, +1 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
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.
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.
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.
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
Related MCP Connectors
Give AI agents secure access to RevDesk calling, SMS, phone numbers, caller IDs, and usage.
Create, configure and manage an AI phone receptionist. Requires a Fonixia account.
Read, write and run Odoo actions from any AI app, as each user, with approval rules per colleague.
Connect assistants to your company tools with per-person, per-action grants and a full audit log.
1
Related MCP Servers
AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage dSIPRouter operations such as endpoint groups, carrier groups, inbound mappings, and call data retrieval through natural language.Apache 2.0- AlicenseNot gradedqualityCmaintenanceEnables 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
- AlicenseBqualityDmaintenanceEnables AI assistants to manage Proxmox VE infrastructure, including VMs, containers, storage, network, high availability, replication, SDN, and node administration.10017 npmMIT

ictpbx-mcpofficial
AlicenseAqualityBmaintenanceThis 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.562 npm16MIT