Yeastar P Series PBX

Yeastar MCP Server

MCP server for the Yeastar P-Series PBX System OpenAPI - read-only visibility into extensions, extension groups, trunks, inbound/outbound routes, IVR menus, ring groups, queues (including live call/agent status), the company contact directory, call detail records (CDR), call reports, backup metadata, and certificate metadata, for AI assistants and the WYRE Conduit gateway.

Appliance/Edition Scope

This connector targets the P-Series Appliance Edition's OpenAPI, base path openapi/v1.0. Per Yeastar's own developer docs (help.yeastar.com, "P-Series Appliance Edition Developer Guide"), the API is only supported on:

• Hardware models P550, P560, and P570 running PBX firmware 37.7.0.16 or later. Other Appliance Edition hardware (e.g. P510) is not documented as supporting the API at all - the docs state functionality "is only supported on P550, P560, and P570" without qualification.
• The docs do not describe any narrower per-endpoint model restriction beyond that - every endpoint this connector implements is covered by the same P550/P560/P570 + firmware-37.7.0.16+ statement.

Cloud Edition is a separate product with its own developer guide and its own OpenAPI surface (same openapi/v1.0 base path structure, firmware requirement documented as 84.7.0.17+), which this connector's request/response shapes were not independently verified against - Appliance and Cloud Edition guides diverge in places (e.g. Cloud Edition additionally documents a v2.0 CDR surface not covered here). If a customer runs Cloud Edition, treat this connector as unverified, not confirmed-incompatible - most of the base OpenAPI mechanics (token exchange, response envelope, pagination) are described identically in both guides, but no endpoint here has been tested against a live Cloud Edition instance.

Software Edition (self-hosted, non-appliance) and any other P-Series variant are out of scope - not mentioned in the Appliance Edition API-support statement above, and not evaluated for this connector.

If a customer's actual hardware/edition is unknown, verify against the PBX web portal (Settings -> About, or the model shown in yeastar_get_system_information) before assuming this connector will work - a PBX outside P550/P560/P570 (Appliance) or Cloud Edition will very likely reject get_token outright with the API feature toggle unavailable in its portal at all.

Authentication

Each Yeastar P-Series PBX is its own appliance, with its own domain/IP and its own credentials - there is no shared hosted API endpoint. A customer enables the API themselves in their PBX's web portal (Integrations -> API, toggle "API" on) and generates a Client ID and Client Secret there. This is not a browser-based OAuth consent flow - the customer pastes the resulting Client ID/Secret directly into the connect form, the same shape as this fleet's other self-hosted/BYO-instance connectors (e.g. Hudu, IT Glue), not the shared-app Authorization Code flow used for SaaS vendors like Cork.

This connector exchanges the Client ID/Secret for a short-lived access token itself - it never proxies them directly into a PBX request. Per Yeastar's docs (POST /openapi/v1.0/get_token), the wire format is genuinely {"username": "<Client ID>", "password": "<Client Secret>"} - Yeastar's own docs are explicit that these fields are the Client ID/Secret ("obtain the username from the Client ID on PBX web portal"), not a separate credential; this connector preserves that field naming rather than renaming it, since it's what the vendor's API actually expects on the wire.

Token lifetime and caching. Access tokens expire after 30 minutes; refresh tokens after 24 hours. Yeastar also caps each application to 8 simultaneous valid tokens. Because of that cap, this connector does not mint a fresh token on every tool call - src/client.ts caches the access token in memory, keyed by appliance + Client ID + Client Secret, and reuses it across calls until it's within 60 seconds of expiring. On a TOKEN EXPIRED response (errcode 10004), it transparently mints a fresh token and retries the failed call exactly once. This is a deliberate deviation from the pattern in this fleet's other connectors (which mint per-request or hold a single static key) - it exists because Yeastar's token model genuinely requires it, not as an optimization for its own sake: without caching, any session making more than 8 tool calls within a 30-minute window would start failing with MAX LIMITATION EXCEEDED (errcode 60002) from Yeastar itself.

In gateway mode, the three credential fields arrive per-request via X-Yeastar-Pbx-Domain / X-Yeastar-Client-Id / X-Yeastar-Client-Secret headers, injected by the Conduit gateway. A /mcp request missing any of those headers is rejected with 401 and does not fall back to YEASTAR_* in the process environment. In local/stdio mode, and in HTTP AUTH_MODE=env, they're read from YEASTAR_PBX_DOMAIN / YEASTAR_CLIENT_ID / YEASTAR_CLIENT_SECRET.

HTTP also requires service-to-service auth. With CONDUIT_S2S_SECRET set, every /mcp request must include X-Gateway-S2S. The header value is t=<unix seconds>,v1=<hex hmac-sha256>. The MAC is HMAC-SHA256 over the ASCII message t=<unix seconds> (the same t= prefix that appears in the header), keyed by CONDUIT_S2S_SECRET, and encoded as lowercase hex. The timestamp must be within 300 seconds of the server clock. A missing or invalid header returns 401 before vendor credentials are read. The secret is never written to logs. /health and /healthz stay unauthenticated and do not read credentials. The stdio transport does not use CONDUIT_S2S_SECRET.

Every request also passes a mandatory User-Agent: OpenAPI header - Yeastar's API rejects requests missing it (errcode 40002, "PARAMETER ERROR").

Defensive field-stripping. Trunk configuration commonly carries SIP registration secrets (auth/register passwords) inline in the same object a read returns, and Yeastar's schema for these objects isn't machine-verifiable from the docs alone. Every response from every tool in this connector - not just trunk tools - passes through stripSecretFields() before it ever reaches the model: any object key matching /secret|password|pwd/i, at any depth, is dropped. This is a blanket safety net on top of, not instead of, the endpoint-level exclusions below (extension/getpassword and conference/viewpassword are never called at all).

Credential-scope finding

Structurally verified (this codebase): this connector's src/client.ts implements exactly one HTTP verb function, doGet - there is no doPost/doPut/doDelete anywhere in this codebase, so it is incapable of issuing a write/control/delete request to the PBX regardless of what the credential itself is permitted to do. src/__tests__/tool-scope.test.ts pins the exact 26-tool set and asserts no tool name matches a write/control/credential-exposing token list.

Vendor-documented, not independently verified: whether the PBX's own admin portal offers any way to scope a Client ID/Secret pair to read-only access is not documented. Per help.yeastar.com's "Enable Yeastar P-Series PBX API" page, enabling the API surfaces exactly one toggle ("API" on/off) plus an optional IP-restriction allowlist and status-monitor configuration - no permission-group, role, or scope selection is described anywhere in that flow. This differs from e.g. Cisco Duo (cisco-duo-mcp), where the vendor's own admin panel offers explicit Grant Read Resource / Grant Write Resource toggles per integration. The practical implication: a Client ID/Secret pair generated for this connector is, as far as Yeastar's own documentation shows, capable of the PBX's full write/control API even though this connector's code never exercises that capability. The only vendor-side compensating control documented is the optional IP-restriction allowlist (scope the credential to only be usable from Conduit's egress IP(s)) - recommend enabling it. If a narrower credential-scoping mechanism does exist and simply isn't documented publicly, it wasn't found during this connector's build and should be treated as unconfirmed.

Configuration

Tools

All 26 tools are read-only. yeastar_get_trunk is additionally classified sensitive in Conduit's VENDOR_TOOL_CONFIG given trunk config's proximity to telephony secrets, even after field-stripping.

System

• yeastar_get_system_information - this appliance's model, firmware version, hostname.
• yeastar_get_system_capacity - current usage against licensed extension/trunk/concurrent-call capacity.

Extensions

• yeastar_list_extensions - list extensions with basic info and per-device online/presence status.
• yeastar_get_extension - full detail for a single extension (never includes its password).

Extension Groups

• yeastar_list_extension_groups - list extension groups.
• yeastar_get_extension_group - full detail (member extensions) for one group.

Trunks

• yeastar_list_trunks - list configured trunks.
• yeastar_get_trunk - full detail for a single trunk, with secret-shaped fields stripped.
• yeastar_list_itsp_trunks - list ITSP (VoIP provider) templates available for trunk creation.

Routes

• yeastar_list_inbound_routes / yeastar_get_inbound_route - inbound call routing.
• yeastar_list_outbound_routes / yeastar_get_outbound_route - outbound call routing.

IVR

• yeastar_list_ivrs / yeastar_get_ivr - auto-attendant menus.

Ring Groups

• yeastar_list_ring_groups / yeastar_get_ring_group.

Queues

• yeastar_list_queues / yeastar_get_queue - queue configuration.
• yeastar_get_queue_call_status - live calls waiting/in-progress in a queue.
• yeastar_get_queue_agent_status - live login/pause state of a queue's agents.

Directory

• yeastar_list_company_contacts - the shared company-wide contact directory.

CDR

• yeastar_list_cdr - call detail records, optionally bound by start_time/end_time.

Call Reports

• yeastar_list_call_reports - aggregated call statistics, optionally bound by start_time/end_time.

Backups

• yeastar_list_backups - backup metadata (name, time, size) for monitoring backup health.

Certificates

• yeastar_list_certificates - TLS certificate metadata (name, domain, expiry) for monitoring cert expiry.

Scope

This is a deliberately narrow, read-only v1 surface. src/client.ts implements exactly one HTTP verb function (doGet) - there is no doPost/doPut/doDelete anywhere in this codebase, so every write/control exclusion below is structurally enforced, not just documented. src/__tests__/tool-scope.test.ts pins the exact 26-tool set.

Operation names below are drawn from Yeastar's own "API Interfaces & Events Summary" reference page (help.yeastar.com, P-Series Appliance Edition Developer Guide) and cross-referenced against individual endpoint doc pages where noted.

A namespacing note that matters for this list: several of Yeastar's own delete/control operations use HTTP GET in their own reference summary (e.g. extension/delete, queue/agent_login) rather than DELETE/POST - this connector excludes them by operation semantics (they mutate or act), not by HTTP method alone. "GET-only by construction" above describes this connector's own verb function, not a claim that every Yeastar GET-method endpoint is safe to call.

Hard-excluded - credential-exposing (never implemented)

• extension/getpassword - returns an extension's live SIP/portal password.
• conference/viewpassword - returns a conference room's live password.

Hard-excluded - GET-verb operations that are actually actions, not reads (never implemented)

• del_token - revokes the current API token.
• extension/delete, extension_group/delete, organization/delete, trunk/delete, company_contact/delete, phonebook/delete, inbound_route/delete, outbound_route/delete, vm/delete, vm/delete_extension_vm, extension_vm_greeting/delete, vm_greeting/delete, ivr/delete, ringgroup/delete, queue/delete, conference/delete, paging/delete, pin_list/delete, block_numbers/delete, allow_numbers/delete, message_channel/delete, message_queues/delete, message_campaign/delete, message_session/delete, certificate/delete, backup/delete, wakeupcall/delete - object deletes.
• queue/agent_login, queue/agent_pause, agent/login, agent/pause - logs an agent in/out of a queue or changes their pause state.

Hard-excluded - documented write/create/update/provisioning operations (never implemented)

• System: system/sendemail.
• Extensions: extension/create, extension/update, extension/send_welcome_email, extension/uploadtempavatarfile.
• Extension Groups: extension_group/create, extension_group/update.
• Organization: organization/create, organization/update.
• Trunks: trunk/create, trunk/update.
• Contacts/Phonebook: company_contact/create, company_contact/update, phonebook/create, phonebook/update.
• Auto Provisioning: phone/batchcreate, phone/batchupdate, phone/batchreprovision, phone/batchreboot, phone/batchdelete.
• Routes: inbound_route/create, inbound_route/update, outbound_route/create, outbound_route/update.
• Voicemail: vm/create, vm/update, extension_vm_greeting/upload, vm_greeting/upload.
• IVR: ivr/create, ivr/update.
• Ring Groups: ringgroup/create, ringgroup/update, ringgroup/updateoptions.
• Queues: queue/create, queue/update, queue/honor_wrapup_time, queue_pause_reason/update, queue_option/update.
• Conference: conference/create, conference/start_interim_conference, conference/invite_member, conference/kick_member, conference/mute_member, conference/unmute_member, conference/update.
• Paging: paging/create, paging/update.
• Recording/Auto settings: autorecord/update.
• PIN & Number Control: pin_list/create, pin_list/update, block_numbers/create, block_numbers/update, allow_numbers/create, allow_numbers/update.
• Call Notes/Messaging: callnotes/update, message_channel/uploadphoto, message_channel/create, message_channel/createlivechat, message_channel/update, message_channel/updatelivechat, message_queue/create, message_queue/update, message_campaign/create, message_campaign/update, message_campaign/retry, message_session/transfer, message_session/close, message_session/archive, message_session/unarchive, message/batchupload, message/send, message/reaction.
• Voice Prompts: play_list/create, custom_prompt/upload.
• Infrastructure: webserver/update, certificate/upload, certificate/create, certificate/update, backup/create.
• API Feature Settings: extension_status_monitor/update, trunk_status_monitor/update, webhook/update.
• CDR: cdr/updateoption, cdr/updatedownloadoption.
• Hotel: wakeupcall/create, wakeupcall/update, hotel/checkout.
• SMS: sms/create.
• Call Control: call/dial, call/accept_inbound, call/refuse_inbound, call/listen, call/hold, call/unhold, call/mute, call/unmute, call/park, call/directly_forward_to_voicemail, call/transfer, call/add_member, call/play_prompt, call/hangup, call/record_start, call/record_pause, call/record_unpause.
• uaCSTA Call Control: uacsta_call/accept, uacsta_call/refuse, uacsta_call/hangup.

Hard-excluded - bulk content, audio, or unverified-secret-safety (never implemented)

• recording/list, recording/search, recording/download, recording/playtoextension - call recording audio.
• vm/query, vm/get, vm/download, vm_group/list, vm_global_greeting/list, extension_vm_greeting/list, vm_greeting/list, extension_vm_greeting/record, extension_vm_greeting/play, extension_vm_greeting/download, vm_greeting/record, vm_greeting/play, vm_greeting/download - voicemail message content, audio, and personal greetings.
• backup/download - the actual backup file, which can embed configuration secrets. (backup/list, metadata only, is implemented.)
• system_log/list, system_log/download - system logs; content not independently verified for secret-safety and no field-level stripping equivalent confirmed sufficient for arbitrary log lines.
• certificate/get, certificate/query - full certificate detail beyond list metadata; not evaluated for whether private key material could appear. (certificate/list, metadata only, is implemented.)

Out of v1 scope (read-only, not implemented for narrowness - could be added later as a deliberate follow-up)

• Messaging/SMS/chat: message_channel/*, message_queue/*, message_campaign/*, message_session/*, message/get, message/query - out of scope for a voice-PBX-focused v1.
• Paging: paging/list, paging/search, paging/get, paging/query.
• Conference: conference/list, conference/search, conference/get, conference/query, query_interim_conference, conference/query_ongoing_conference.
• PIN lists & number controls: pin_list/*, block_numbers/*, allow_numbers/* (read variants).
• Voice prompts: play_list/list, play_list/get, play_list/query, custom_ringtone/list.
• Personal phonebook (distinct from company_contact, which is implemented): phonebook/list, phonebook/search, phonebook/get, phonebook/query.
• Auto provisioning: phone/search, phone/get, auto_provisioning/compatibility.
• Organization: organization/list, organization/search, organization/get, organization/query.
• Call notes: callnotes/get.
• API feature settings (meta-config of the API surface itself, not PBX telephony state): extension_status_monitor/list, trunk_status_monitor/list, webhook/query, webhook/test.
• Hotel management: wakeupcall/list, wakeupcall/get, wakeupcall/query.
• Live call-state queries grouped under Yeastar's own "Call Control" category: call/query, call/park_status - conservatively excluded despite being nominally read-only, consistent with this connector's hard scope boundary against anything the vendor itself categorizes as call control.
• Reference data: timezone/list.
• System: system/get_menuoptions - UI menu metadata, not PBX configuration/monitoring data.
• CDR/report variants beyond what's implemented: cdr/search, cdr/download, cdr/getoption, cdr/getdownloadoption (v1.0); call_report/detail, call_report/download; call_schedule_report/list, call_schedule_report/download; myreport/list. The separate Cloud Edition openapi/v2.0 CDR surface is out of scope entirely (see Appliance/Edition Scope above).
• /search and /query variants: for every resource type that also documents /search and /query alongside /list and /get (extension, extension_group, trunk, inbound_route, outbound_route, ivr, ringgroup, queue, company_contact, pin_list, block_numbers, allow_numbers, message_channel, message_queue, message_campaign, message_session, play_list, certificate, backup, wakeupcall), this connector implements /list + /get only. /search is a filtered list and /query is a bulk multi-ID detail fetch - both overlap materially with list+get for this connector's monitoring use case.

They can be added as a follow-up if there's demand, after a deliberate scope decision - not by default.

Development

npm install
npm run build
npm test
npm run lint   # tsc --noEmit

# HTTP refuses to start until CONDUIT_S2S_SECRET is set
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" npm run start:http

# Local HTTP only, without a service-to-service secret (binds 127.0.0.1)
MCP_ALLOW_INSECURE_DEV=1 npm run start:http

Docker

The image listens on 0.0.0.0 inside the container (MCP_HTTP_HOST) and defaults to AUTH_MODE=gateway. Startup still refuses to run without CONDUIT_S2S_SECRET. Publish the port on loopback. In gateway mode, Yeastar credentials arrive on each request as headers; they are not read from the environment.

docker build -t yeastar-mcp .
docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -p 127.0.0.1:8080:8080 \
  yeastar-mcp

Compose refuses to start when CONDUIT_S2S_SECRET is unset, sets AUTH_MODE=gateway, does not inject YEASTAR_PBX_DOMAIN / YEASTAR_CLIENT_ID / YEASTAR_CLIENT_SECRET, and publishes 127.0.0.1:8080:8080:

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

Single-tenant HTTP (AUTH_MODE=env) still requires the S2S secret, then uses the YEASTAR_* environment variables. It is separate from the gateway Compose service:

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e YEASTAR_PBX_DOMAIN=https://pbx.example.com:8088 \
  -e YEASTAR_CLIENT_ID=... \
  -e YEASTAR_CLIENT_SECRET=... \
  -p 127.0.0.1:8080:8080 \
  yeastar-mcp

X-Gateway-S2S for either mode is t=<unix seconds>,v1=<hmac-sha256 hex of the string t=<unix seconds>>, signed with CONDUIT_S2S_SECRET.