ictinnovations/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.
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
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:
- -i is 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.internal on Mac and Windows, or add --network host on 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 |
|---|---|---|
| ASTERISK_AMI_HOST | *(required to enable)* | Hostname or IP of the Asterisk box |
| ASTERISK_AMI_PORT | 5038 | AMI port from manager.conf |
| ASTERISK_AMI_USERNAME | | AMI user |
| ASTERISK_AMI_PASSWORD | | AMI secret |
| ASTERISK_AMI_TLS | false | Set true if tlsenable=yes |
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
| Variable | Default | Notes |
|---|---|---|
| FREESWITCH_ESL_HOST | *(required to enable)* | Hostname or IP of the switch |
| FREESWITCH_ESL_PORT | 8021 | Inbound ESL port |
| FREESWITCH_ESL_PASSWORD | ClueCon | From event_socket.conf.xml |
Shared
| Variable | Default | Notes |
|---|---|---|
| PBX_MCP_ALLOW_WRITE | false | Unlocks call control. Read the safety section first |
| PBX_MCP_TIMEOUT_MS | 10000 | Per command timeout |
Provisioning (Asterisk only, opt-in)
| Variable | Default | Notes |
|---|---|---|
| PBX_MCP_ALLOW_PROVISION | false | Registers the six trunk and extension tools. Independent of PBX_MCP_ALLOW_WRITE |
| PBX_MCP_TRUNK_ALLOW | *(unset)* | Comma-separated IPv4 CIDRs and hostnames a trunk may point at. **Unset means asterisk_trunk_create is refused** |
| PBX_MCP_CONTEXT_ALLOW | *(unset)* | Comma-separated dialplan contexts new objects may use. Unset means every create is refused |
| PBX_MCP_PJSIP_FILE | pjsip_mcp.conf | The one include file provisioning writes to. A bare pjsip_*.conf name (never pjsip.conf, manager.conf or any other file) |
Claude Desktop