pbx-mcp — Claude Code MCP server: Asterisk and FreeSWITCH
Lets an AI assistant query a live Asterisk or FreeSWITCH PBX: active channels, endpoints, dialplan and trunk registration.
claude mcp add --env ASTERISK_AMI_HOST=<ASTERISK_AMI_HOST> --env ASTERISK_AMI_PORT=<ASTERISK_AMI_PORT> --env ASTERISK_AMI_USERNAME=<ASTERISK_AMI_USERNAME> --env ASTERISK_AMI_PASSWORD=<ASTERISK_AMI_PASSWORD> --env ASTERISK_AMI_TLS=<ASTERISK_AMI_TLS> --transport stdio pbx-mcp -- npx -y pbx-mcpWhat pbx-mcp does
pbx-mcp gives your assistant one tool surface instead of two command vocabularies. Asterisk talks AMI, FreeSWITCH talks ESL, and running both used to mean constant switching. Now you can ask which extensions are offline and the model picks the right call on the switch itself.
Twelve tools ship in read-only mode, six per engine. The four call-control tools — asterisk_originate, asterisk_hangup, freeswitch_originate and freeswitch_hangup — stay out of sight until PBX_MCP_ALLOW_WRITE=true is set. Asterisk provisioning is a separate opt-in: six trunk and extension tools appear under PBX_MCP_ALLOW_PROVISION, and trunk creation is refused while PBX_MCP_TRUNK_ALLOW is empty.
Configuration lives in environment variables. Fill in the Asterisk block, the FreeSWITCH block, or both, and the server registers tools only for what you configured. Node 18 or newer is required, and a prebuilt Docker image is available. On the AMI side, a user with read = system,call,command and write = command is enough; add originate only when you plan to enable write mode.
What it helps with
- see which channels are live and who is calling
- find out why a SIP trunk will not register
- dump a dialplan context or a single extension
- check PJSIP endpoint state and contact count
- run an arbitrary Asterisk CLI command
Example prompts for the agent
- List every active channel on Asterisk with caller ID and duration
- Why is my SIP trunk not registering? Check the gateway status
- Dump the dialplan for context
from-internal
How to install pbx-mcp
Platform CLI
claude mcp add --env ASTERISK_AMI_HOST=<ASTERISK_AMI_HOST> --env ASTERISK_AMI_PORT=<ASTERISK_AMI_PORT> --env ASTERISK_AMI_USERNAME=<ASTERISK_AMI_USERNAME> --env ASTERISK_AMI_PASSWORD=<ASTERISK_AMI_PASSWORD> --env ASTERISK_AMI_TLS=<ASTERISK_AMI_TLS> --transport stdio pbx-mcp -- npx -y pbx-mcpReplace <…> with your own values. 5 more environment variables are in the server README
Platform CLI
codex mcp add pbx-mcp --env ASTERISK_AMI_HOST=<ASTERISK_AMI_HOST> --env ASTERISK_AMI_PORT=<ASTERISK_AMI_PORT> --env ASTERISK_AMI_USERNAME=<ASTERISK_AMI_USERNAME> --env ASTERISK_AMI_PASSWORD=<ASTERISK_AMI_PASSWORD> --env ASTERISK_AMI_TLS=<ASTERISK_AMI_TLS> -- npx -y pbx-mcpReplace <…> with your own values. 5 more environment variables are in the server README
Config file
{
"mcpServers": {
"pbx-mcp": {
"command": "npx",
"args": [
"-y",
"pbx-mcp"
],
"env": {
"ASTERISK_AMI_HOST": "<ASTERISK_AMI_HOST>",
"ASTERISK_AMI_PORT": "<ASTERISK_AMI_PORT>",
"ASTERISK_AMI_USERNAME": "<ASTERISK_AMI_USERNAME>",
"ASTERISK_AMI_PASSWORD": "<ASTERISK_AMI_PASSWORD>",
"ASTERISK_AMI_TLS": "<ASTERISK_AMI_TLS>"
}
}
}
}Replace <…> with your own values. 5 more environment variables are in the server README
Config file
{
"servers": {
"pbx-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"pbx-mcp"
],
"env": {
"ASTERISK_AMI_HOST": "<ASTERISK_AMI_HOST>",
"ASTERISK_AMI_PORT": "<ASTERISK_AMI_PORT>",
"ASTERISK_AMI_USERNAME": "<ASTERISK_AMI_USERNAME>",
"ASTERISK_AMI_PASSWORD": "<ASTERISK_AMI_PASSWORD>",
"ASTERISK_AMI_TLS": "<ASTERISK_AMI_TLS>"
}
}
}
}Replace <…> with your own values. 5 more environment variables are in the server README
Platform CLI
gemini mcp add -e ASTERISK_AMI_HOST=<ASTERISK_AMI_HOST> -e ASTERISK_AMI_PORT=<ASTERISK_AMI_PORT> -e ASTERISK_AMI_USERNAME=<ASTERISK_AMI_USERNAME> -e ASTERISK_AMI_PASSWORD=<ASTERISK_AMI_PASSWORD> -e ASTERISK_AMI_TLS=<ASTERISK_AMI_TLS> pbx-mcp npx -y pbx-mcpReplace <…> with your own values. 5 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about pbx-mcp
How do I install pbx-mcp in Claude Code?
Run claude mcp add pbx-mcp -e ASTERISK_AMI_PASSWORD=<ASTERISK_AMI_PASSWORD> -e FREESWITCH_ESL_PASSWORD=<FREESWITCH_ESL_PASSWORD> -- npx -y pbx-mcp, replacing the placeholders with your own credentials.
What does pbx-mcp do?
It exposes read tools for Asterisk over AMI and FreeSWITCH over ESL: channels, endpoints, dialplan and status. Call control is unlocked by a separate flag.
What AMI permissions does it need?
At minimum read = system,call,command and write = command. The originate permission matters only if you turn on write mode with PBX_MCP_ALLOW_WRITE.
