pbx-mcp
The server allows AI assistants to inspect and optionally control Asterisk and FreeSWITCH PBXs through a unified interface. It provides:
Asterisk monitoring: view server status (version, uptime, calls), list active channels (with filtering), check PJSIP endpoint registration (fallback to chan_sip), inspect dialplan, and execute read-only CLI commands.
FreeSWITCH monitoring: view server status (version, uptime, sessions), list active channels, check SIP registrations on Sofia profiles, inspect Sofia profile and gateway status, and execute read-only API commands.
Call control: originate calls and hangup channels become available when write mode is enabled (PBX_MCP_ALLOW_WRITE=true).
Safety: operates read-only by default; write tools are hidden unless allowed. Additional safeguards include command allow-listing, word-level scanning for destructive FreeSWITCH commands, shell metacharacter rejection, AMI header injection blocking, and output clamping.
Configuration: set environment variables for Asterisk AMI and/or FreeSWITCH ESL credentials; only tools for configured systems are registered. Supports connecting to both PBX types simultaneously. Runs via stdio with npm/npx or Docker.
Provides tools for inspecting and controlling an Asterisk PBX, including status, channels, endpoints, dialplan, CLI commands, and call control (originate/hangup).
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., "@pbx-mcp which extensions are offline right now?"
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.
pbx-mcp
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.
Related MCP server: VoIPbin MCP Server
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:

The four write tools, asterisk_originate, asterisk_hangup, freeswitch_originate and freeswitch_hangup, stay hidden until you set PBX_MCP_ALLOW_WRITE=true.
Install
npm install -g pbx-mcpOr run it straight from npx, which is what most MCP client configs do:
npx -y pbx-mcpYou 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.
docker run -i --rm \
-e ASTERISK_AMI_HOST=10.0.0.10 \
-e ASTERISK_AMI_USERNAME=mcp \
-e ASTERISK_AMI_PASSWORD=change-me \
ghcr.io/ictinnovations/pbx-mcpThe 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
Variable | Default | Notes |
| (required to enable) | Hostname or IP of the Asterisk box |
|
| AMI port from |
| AMI user | |
| AMI secret | |
|
| Set |
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.
[mcp]
secret = change-me
read = system,call,command
write = commandFreeSWITCH
Variable | Default | Notes |
| (required to enable) | Hostname or IP of the switch |
|
| Inbound ESL port |
|
| From |
Shared
Variable | Default | Notes |
|
| Unlocks call control. Read the safety section first |
|
| Per command timeout |
Provisioning (Asterisk only, opt-in)
Variable | Default | Notes |
|
| Registers the six trunk and extension tools. Independent of |
| (unset) | Comma-separated IPv4 CIDRs and hostnames a trunk may point at. Unset means |
| (unset) | Comma-separated dialplan contexts new objects may use. Unset means every create is refused |
|
| The one include file provisioning writes to. A bare |
Claude Desktop
Add this to claude_desktop_config.json:
{
"mcpServers": {
"pbx": {
"command": "npx",
"args": ["-y", "pbx-mcp"],
"env": {
"ASTERISK_AMI_HOST": "10.0.0.10",
"ASTERISK_AMI_USERNAME": "mcp",
"ASTERISK_AMI_PASSWORD": "change-me",
"FREESWITCH_ESL_HOST": "10.0.0.11",
"FREESWITCH_ESL_PASSWORD": "ClueCon"
}
}
}
}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:
{
"mcpServers": {
"pbx": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "ASTERISK_AMI_HOST",
"-e", "ASTERISK_AMI_USERNAME",
"-e", "ASTERISK_AMI_PASSWORD",
"ghcr.io/ictinnovations/pbx-mcp"
],
"env": {
"ASTERISK_AMI_HOST": "10.0.0.10",
"ASTERISK_AMI_USERNAME": "mcp",
"ASTERISK_AMI_PASSWORD": "change-me"
}
}
}
}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
Tool | What it does |
| Version, uptime, active calls and calls processed |
| Every live channel with caller ID, state, bridge, duration and dialplan position. Optional substring filter |
| PJSIP endpoints with device state and contact count. Falls back to |
| Dumps a context, or one extension inside a context |
| Any CLI command, subject to the safety policy below |
| Shows which live channels a hangup would drop, without dropping them |
| Places a call. Write mode only |
| Kills a channel by name. Write mode only |
FreeSWITCH
Tool | What it does |
| Version, uptime, current and maximum sessions |
| Every live call leg from |
| Registered users on a Sofia profile, with contact URI, user agent and expiry |
| Every SIP profile and gateway, including whether trunks are registered upstream |
| Any API command, subject to the safety policy below |
| Shows which live legs a hangup would drop, without dropping them |
| Places a call. Write mode only |
|
|
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.
Tool | What it does |
| IP-authenticated trunk: endpoint, aor and identify. Fields: |
| List or remove trunks this server created |
| A SIP endpoint phones register to (endpoint, aor, auth), not a dialplan extension. Fields: |
| List or remove extensions this server created. Passwords are never listed |
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:touch /etc/asterisk/pjsip_mcp.confAdd this single line at the end of
pjsip.conf. Nothing else inpjsip.confis ever touched:#include pjsip_mcp.confGive the AMI user the extra permissions provisioning needs.
configis forUpdateConfig/GetConfig,commandfor the reload and verify steps,originateonly if you also use write mode:[mcp] secret = change-me deny = 0.0.0.0/0.0.0.0 permit = 192.0.2.0/24 read = system,call,command write = command,originate,configTrunks 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:
PBX_MCP_ALLOW_PROVISION=true
PBX_MCP_TRUNK_ALLOW=192.0.2.0/24,198.51.100.0/24
PBX_MCP_CONTEXT_ALLOW=from-trunk,from-internalPreview a trunk with
asterisk_trunk_createanddry_run=true:{ "name": "carrier1", "host": "192.0.2.10", "port": 5060, "transport": "udp", "codecs": ["ulaw", "alaw"], "context": "from-trunk", "dry_run": true }which returns
[mcp-carrier1] type=endpoint transport=transport-udp context=from-trunk disallow=all allow=ulaw,alaw aors=mcp-carrier1 [mcp-carrier1] type=aor contact=sip:192.0.2.10:5060 [mcp-carrier1] type=identify endpoint=mcp-carrier1 match=192.0.2.10Run 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
git clone https://github.com/ictinnovations/pbx-mcp.git
cd pbx-mcp
npm install
npm run build
npm startThe 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-nodefreeswitch-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
src/
index.ts entry point, config to transport wiring
ami.ts Asterisk Manager Interface client
esl.ts FreeSWITCH Event Socket Layer client
config.ts environment config and the command safety policy
tools/
asterisk.ts Asterisk tool definitions
freeswitch.ts FreeSWITCH tool definitions
format.ts text table and truncation helpersContributing
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.
Available Tools
12 toolsasterisk_channelsList active Asterisk channelsARead-only
Every channel currently up on the PBX, with caller ID, state, bridge, duration and the dialplan location it is sitting in. This is the tool for 'what calls are live right now'.
Inputs: filter.
asterisk_cliRun an Asterisk CLI commandBRead-only
Run a command through the Asterisk CLI and return its raw output. In the default read-only mode only inspection commands such as 'core show', 'pjsip show' and 'queue show' are permitted. Set PBX_MCP_ALLOW_WRITE=true to lift that restriction.
Inputs: command (required).
asterisk_dialplanShow dialplanARead-only
Dump the dialplan for a context, or for one extension within a context. Useful for tracing where a call would go before placing it.
Inputs: context (required), extension.
asterisk_endpointsList PJSIP endpoints and registration stateARead-only
PJSIP endpoints with their device state and how many contacts are registered. Use this to answer 'is extension 1001 registered' or 'which phones are offline'. Falls back to chan_sip peers on older installations.
Inputs: filter.
asterisk_hangup_previewPreview what a hangup would dropARead-only
Show which live channels a hangup would affect, without touching them. Takes the same channel argument as asterisk_hangup and reports the exact match plus any near misses, so you can see the blast radius before dropping a call. Always available, including in read-only mode.
Inputs: channel (required).
asterisk_statusAsterisk statusARead-only
Core status of the Asterisk server: version, uptime, active calls and calls processed. Use this first to confirm the PBX is reachable before running other Asterisk tools.
Inputs: no named parameters.
freeswitch_apiRun a FreeSWITCH API commandARead-only
Run a command through the FreeSWITCH event socket and return its raw output. In the default read-only mode only inspection commands such as 'status', 'show' and 'sofia status' are permitted. Set PBX_MCP_ALLOW_WRITE=true to lift that restriction.
Inputs: command (required).
freeswitch_channelsList active FreeSWITCH channelsARead-only
Every call leg currently up on the switch, as returned by 'show channels'. This is the tool for 'what calls are live right now' on FreeSWITCH.
Inputs: filter.
freeswitch_hangup_previewPreview what a hangup would dropARead-only
Show which live call legs a hangup would affect, without touching them. Takes the same UUID argument as freeswitch_hangup and reports the matching channel plus the leg it is bridged to, so you can see the blast radius first. Always available, including in read-only mode.
Inputs: uuid (required).
freeswitch_registrationsList SIP registrationsARead-only
Registered SIP users on a Sofia profile, with contact URI, user agent and expiry. Use this to answer 'is this extension registered' or 'which devices dropped off'.
Inputs: profile.
freeswitch_sofia_statusSofia SIP profile and gateway statusARead-only
State of every Sofia SIP profile and gateway, including whether trunks are registered upstream. This is where to look when outbound calls fail but the switch itself is healthy.
Inputs: profile.
freeswitch_statusFreeSWITCH statusARead-only
Core status of the FreeSWITCH server: version, uptime, current and maximum sessions. Use this first to confirm the switch is reachable before running other FreeSWITCH tools.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Tools are cleanly partitioned by platform prefix (asterisk_* vs freeswitch_*) and each resource is distinct: channels vs endpoints vs status vs sofia profiles answer different questions. The main overlap is that asterisk_cli/freeswitch_api can reproduce nearly everything the specialized tools do, but the descriptions steer agents toward the purpose-built tools and the read-only default limits the damage.
Consistent snake_case with a predictable platform_resource pattern (asterisk_channels, freeswitch_registrations, etc.), mirrored neatly across both subsystems. The only blemish is that the raw-command tool is called asterisk_cli on one side and freeswitch_api on the other, so the parallel naming breaks for that one pair.
12 tools split roughly six-and-six across two PBX platforms, with each tool earning its place (status, channels, registrations, dialplan/profiles, raw command, hangup preview). Well within a comfortable range for the scope.
Both *_hangup_preview tools explicitly reference an asterisk_hangup / freeswitch_hangup counterpart that does not exist in the surface, leaving the previews as dead ends an agent cannot act on. Read-only inspection is otherwise well covered, but there is no originate, no queue/voicemail-specific tools, and no write path beyond flipping the raw CLI/API escape hatch.
Maintenance
Related MCP Connectors
Open-source MCP gateway with per-agent tool permissions, call approvals and tool-change review.
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
The Telnyx MCP server is an official implementation of the Model Context Protocol that enables AI clients (like Claude Desktop, Cursor, and OpenAI Agents) to interact with Telnyx's telephony, messaging, and AI assistant APIs. It provides comprehensive capabilities including making and managing phone calls, sending SMS/MMS messages, purchasing and configuring phone numbers, creating AI assistants with custom instructions, managing cloud storage buckets, scraping and embedding website content, and handling integration secrets. The server exists as both a local implementation and a remotely hosted version, allowing developers to integrate real-world communication infrastructure directly into AI applications.
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
Related MCP Servers
- FlicenseCqualityDmaintenanceMCP server enabling interaction with Telnyx telephony, messaging, and AI assistant APIs through natural language.46-

VoIPbin MCP Serverofficial
AlicenseBqualityBmaintenanceAn MCP server that enables AI assistants to interact with the VoIPbin CPaaS platform, exposing tools for managing calls, flows, messaging, conferencing, and more.662MIT- AlicenseNot gradedqualityBmaintenanceAn MCP server that enables AI assistants to manage Cisco Unified Communications Manager (CUCM) via AXL SOAP API, supporting provisioning, configuration, and database queries through natural language.199 npm7MIT
- AlicenseNot gradedqualityBmaintenanceAn MCP server enabling AI assistants to make voice calls, send SMS/MMS, and manage group conversations using Twilio and OpenAI.21 npmMIT