
Pbx Mcp
io.github.ictinnovations由 GitHub 帳號 ictinnovations 發布v0.1.4更新於 Oct 26, 2026
Inspect and control Asterisk (AMI) and FreeSWITCH (ESL) PBX servers from your AI assistant.
概覽
一個本機 MCP 伺服器,讓 AI 助理透過 AMI 和 ESL 檢視,並在啟用後控制 Asterisk 與 FreeSWITCH 電話交換機。
- 可以做什麼
- 檢視 Asterisk:狀態、作用中通道、PJSIP 端點、撥號計畫內容,以及在允許清單內的任意 CLI 指令,另有掛斷預覽可顯示受影響通道而不真正掛斷。檢視 FreeSWITCH:狀態、通話分支、Sofia 註冊、SIP 設定檔與閘道、允許清單內的 API 指令,以及掛斷預覽。啟用寫入模式後控制通話:在兩種交換機上發起通話與掛斷通道。啟用佈建功能後管理 Asterisk 中繼與 SIP 分機:建立、列出與刪除,並支援試執行。
- 適用情境
- 適合執行 Asterisk、FreeSWITCH 或兩者兼有的情境,想直接詢問即時狀態,例如哪些分機離線、SIP 中繼為何無法註冊,而不必記住 AMI 和 ESL 指令。也適合在實驗或預備環境中讓助理協助建立中繼與分機。
- 執行需求
- 本機 Node.js 18 或更新版本的執行環境(npm 套件或 Docker 映像),或任何支援 stdio 的 MCP 用戶端。需要能透過網路存取交換機。Asterisk 需設定 ASTERISK_AMI_HOST、ASTERISK_AMI_USERNAME 和 ASTERISK_AMI_PASSWORD,連接埠與 TLS 為選用。FreeSWITCH 需設定 FREESWITCH_ESL_HOST 和 FREESWITCH_ESL_PASSWORD,連接埠為選用。寫入與佈建工具預設關閉,需透過對應開關啟用。
安裝
在 SourceWeft 中
- 開啟 儀表板中的 Pbx Mcp,將其新增到工作區。
- 為需要使用其工具的對話啟用該服務。
Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。
其他 MCP 客戶端
參照 儲存庫 中的啟動說明。
README
pbx-mcp
[pbx-mcp MCP server] [Documentation Status]
An MCP server that lets an AI assistant inspect and control Asterisk and FreeSWITCH.
Ask "which extensions are offline right now?" or "why is my SIP trunk not registering?" and get a real answer from the live switch, not a guess.
Developed by Tahir Almas at ICT Innovations, the team behind ICTCore, ICTContact, ICTDialer, ICTFax and ICTPBX. The AMI and ESL clients in this repo are the same protocol groundwork those products run on.
Why
Debugging a PBX means memorising two very different command sets. Asterisk speaks AMI and a CLI with hundreds of verbs. FreeSWITCH speaks ESL with its own vocabulary. If you run both, you're context switching all day.
pbx-mcp puts a single, well described tool surface in front of both, so your assistant can go from "calls are failing" to sofia status gateway without you spelling out each step.
New here? The user guide walks through PBX setup, client config, worked examples and troubleshooting. This README is the quick reference.
What your assistant sees
Twelve read-only tools, six per engine, each one described well enough that the model picks the right one without being told. This is the server running under the MCP Inspector:
[pbx-mcp tools listed in the MCP Inspector]
The four write tools, asterisk_originate, asterisk_hangup, freeswitch_originate and freeswitch_hangup, stay hidden until you set PBX_MCP_ALLOW_WRITE=true.
Install
Or run it straight from npx, which is what most MCP client configs do:
You need Node 18 or newer.
Docker
There's a prebuilt image if you'd rather not put Node on the machine that talks to your PBX.
The same image is on Docker Hub as ictinnovations/pbx-mcp if that registry is an easier pull for you.
Three things to know:
-iis not optional. The server speaks MCP over stdio, so without stdin attached the container starts and then sits there saying nothing, which looks exactly like a broken server.- There is no port to publish. Nothing listens.
- Your PBX has to be reachable from inside the container. If Asterisk runs on the Docker host itself, swap the IP above for
host.docker.internalon Mac and Windows, or add--network hoston Linux.
The image runs as a non-root user and, like every other way of running this, starts read only.
Configure
Everything comes from environment variables. Set the Asterisk block, the FreeSWITCH block, or both. The server only registers tools for what you've actually configured, so an Asterisk-only shop never sees a FreeSWITCH tool.
Asterisk
Your manager.conf user needs at least read = system,call,command and write = command. Add originate only if you plan to turn on write mode.
FreeSWITCH
Shared
Provisioning (Asterisk only, opt-in)
Claude Desktop
Add this to claude_desktop_config.json:
The same shape works for any MCP client that speaks stdio. There's a copy in examples/claude_desktop_config.json.
To run the container instead of npx, keep the env block and point command at Docker:
Each -e NAME with no value forwards that variable from env into the container, which keeps the secrets out of the argument list.
Tools
Asterisk
FreeSWITCH
Safety
A PBX is not a scratch pad. Reloading a profile drops registrations, and an originate spends real money on a live trunk. So the default posture is read-only and the guards are layered:
Read-only by default. asterisk_cli accepts an allow list of inspection prefixes (core show, pjsip show, dialplan show, queue show and friends). freeswitch_api accepts the same kind of list (status, show, sofia status, db list and friends), matched on the start of the command so the subcommand counts.
The FreeSWITCH list allows subcommands, it does not deny scary words. sofia status reads, sofia profile internal restart isn't on the list, so it's refused. This used to work the other way around, scanning each word against a list of state changing verbs, and that only ever catches the words somebody thought of. conference 3001 kick all walked straight through it. Reported by Electrical-Place-458 on r/mcp.
Write tools aren't registered at all in read-only mode. asterisk_originate and the other three never appear in tools/list unless you set PBX_MCP_ALLOW_WRITE=true. A model can't call a tool it can't see.
The hangup preview tools are always available. asterisk_hangup_preview and freeswitch_hangup_preview show which live channels a hangup would drop without touching them, so you can see the blast radius before setting the write flag, or catch a typo in a channel name before running the real thing. They're read-only by contract but exercise the same matching the write path uses.
Shell metacharacters are rejected on both transports before a command is sent.
AMI header injection is blocked. Every field that lands in an AMI action is checked for carriage returns and newlines, so a caller ID string can't smuggle in an extra header.
Output is clamped to 20,000 characters. One show channels on a busy switch won't flood the context window.
Even with all that, give the AMI user the narrowest permission set that answers your questions, and put the PBX behind a firewall rather than on the public internet.
Provisioning trunks and extensions (Asterisk, opt-in)
Six more tools create, list and delete PJSIP trunks and SIP extensions through AMI UpdateConfig. They are registered only when PBX_MCP_ALLOW_PROVISION=true, and they are separate from write mode: enabling one does not enable the other.
Codecs are ulaw, alaw, g722, g729, opus. Names and numbers match ^[A-Za-z0-9_-]{1,32}$.
One-time setup
-
Create the managed file, empty, beside
pjsip.conf(a missing include is an error), and let Asterisk write to it: -
Add this single line at the end of
pjsip.conf. Nothing else inpjsip.confis ever touched: -
Give the AMI user the extra permissions provisioning needs.
configis forUpdateConfig/GetConfig,commandfor the reload and verify steps,originateonly if you also use write mode: -
Trunks reference a transport named
transport-udp,transport-tcportransport-tls; define the ones you will use inpjsip.conf.
How it works
- Everything goes into the managed file with
UpdateConfig(NewCat,Append,RenameCat,DelCat), thenmodule reload res_pjsip.so, thenpjsip show endpoint mcp-<name>. If Asterisk does not report the endpoint, the change is removed again and the call returns an error. - Every object is named
mcp-<name>. List and delete only act onmcp-sections of the managed file, and a trunk cannot be deleted as an extension or the other way round. - Create refuses a name that already exists.
dry_run=truereturns the exact config block and makes no AMI calls; for an extension the password is shown as a placeholder. - All provisioning calls are serialized in-process, because
UpdateConfigis read-modify-write. Run only one pbx-mcp provisioner per managed file. - An extension registers as
mcp-<number>, not the bare number. PJSIP matches the endpoint and its AOR by the registering username, and every object has to carry themcp-prefix. The create response states the username. - The password is 24 random URL-safe characters from
crypto.randomBytes. It is returned only in the create response, which is the only place it is ever shown or logged; it does exist in the managed file on the PBX, as any SIP password must.
Toll fraud: read this before enabling
A SIP trunk lets calls leave your PBX, and a registrable extension with a context that reaches an outbound route lets anyone who learns the password do the same. Stolen SIP credentials are a leading cause of large telephony bills.
- Point
PBX_MCP_CONTEXT_ALLOWat contexts that cannot dial out to the PSTN unless you really mean it. The context is the only thing that decides what a registered phone or trunk may call. - Keep
PBX_MCP_TRUNK_ALLOWas narrow as you can. Hostnames are compared literally and never resolved, so DNS cannot widen the list. IPv6 is not supported. - An empty allowlist refuses everything: provisioning fails closed.
- Treat the assistant that holds these tools as holding the ability to change who can reach your PBX. Review what it creates (
*_list, ordry_runfirst), and do not expose SIP (5060) or AMI (5038) to the internet. - Prefer a lab or staging PBX when trying this out.
Example flow
Using documentation addresses (RFC 5737) only. Environment:
-
Preview a trunk with
asterisk_trunk_createanddry_run=true:which returns
-
Run it again without
dry_run. A host outside the allowlist, for example203.0.113.5, is refused. -
Create an extension:
{ "number": "1001", "context": "from-internal" }. The reply gives the SIP usernamemcp-1001and the password, once. -
Point a phone at the PBX with those credentials, then check it with
asterisk_endpoints. -
asterisk_extension_listandasterisk_trunk_listshow what exists;asterisk_extension_deletewith1001andasterisk_trunk_deletewithcarrier1remove it again.
Tested against Asterisk 22 (certified 22.8). The PJSIP options used (identify, max_contacts, remove_existing, auth_type=userpass) and the UpdateConfig features (RenameCat, catfilter) are standard, but re-check them on other Asterisk versions. TCP and TLS trunks are generated but were not exercised against a live peer.
Build from source
The AMI and ESL clients have no third party dependencies. Both protocols are just framed text over TCP, and hand rolling them keeps the install small and the behaviour predictable. The only runtime dependencies are the MCP SDK and Zod.
The protocol clients, on their own
If you want to talk to a PBX from your own Node code and don't need MCP at all, the two clients underneath this server are published separately. Same protocol work, no MCP SDK, no Zod, nothing:
- asterisk-ami-node - Asterisk Manager Interface client.
npm install asterisk-ami-node - freeswitch-esl-node - FreeSWITCH Event Socket client, inbound mode.
npm install freeswitch-esl-node
Both are zero dependency, TypeScript, ESM and CommonJS, Node 18 or newer, and tested against mock switches so you can run the suite without a PBX.
Layout
Contributing
Issues and pull requests are welcome. If you're adding a tool, describe it the way you'd describe it to a colleague who has never seen your dialplan. The model picks tools from those descriptions, so a vague one is a broken one.
About
Built and maintained by Tahir Almas, founder of ICT Innovations.
ICT Innovations has shipped open source and commercial telephony since 2005. If pbx-mcp is useful to you, the wider stack behind it might be too:
- ICTCore - open source telephony framework, the base for the products below
- ICTPBX - white label multi tenant IP PBX, with a free community edition on GitHub
- ICTContact - contact center and unified communications
- ICTDialer - auto and predictive dialer
- ICTFax - open source fax server
- asterisk-ami-node and freeswitch-esl-node - the protocol clients from this repo, published on their own
Questions about the commercial products go through the ICT Innovations support portal. Questions about pbx-mcp itself belong in GitHub issues, where everyone can read the answer.
License
MIT. See LICENSE.
來源:README.md,提交 f356cc4
工具
0版本歷史
3- v0.1.4最新Oct 26, 2026
- v0.1.3Oct 9, 2026
- v0.1.2Sep 16, 2026
評分
已滿足適用檢查項的 50%
該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。
- 近 30 天內可連通25 分
請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。
- 已宣告認證方式10 分
請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。
- 已列出工具15 分
請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。
- 描述必需15 分
- 圖示10 分
- 文件15 分
- 授權條款10 分