# pbx-mcp [Health: Active]

**Category:** 💬 Communication  
**Repository:** https://github.com/ictinnovations/pbx-mcp  
**GitHub Stars:** 19  
**npm Downloads (last month):** 612  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/pbx-mcp

## Description
Inspect and control Asterisk (AMI) and FreeSWITCH (ESL) PBX servers from your AI assistant.

## Tools
Capabilities this server exposes over MCP:

- **asterisk_status** — 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.
- **asterisk_channels** — 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'.
- **asterisk_endpoints** — 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.
- **asterisk_dialplan** — Dump the dialplan for a context, or for one extension within a context. Useful for tracing where a call would go before placing it.
- **asterisk_cli** — 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.
- **asterisk_hangup_preview** — 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.
- **freeswitch_status** — 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.
- **freeswitch_channels** — 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.
- **freeswitch_registrations** — 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'.
- **freeswitch_sofia_status** — 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.
- **freeswitch_api** — 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.
- **freeswitch_hangup_preview** — 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.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "pbx-mcp": {
    "command": "npx",
    "args": ["-y","pbx-mcp"],
    "env": {
      "ASTERISK_AMI_HOST": "",
      "ASTERISK_AMI_PORT": "",
      "ASTERISK_AMI_USERNAME": "",
      "ASTERISK_AMI_PASSWORD": "",
      "ASTERISK_AMI_TLS": "",
      "FREESWITCH_ESL_HOST": "",
      "FREESWITCH_ESL_PORT": "",
      "FREESWITCH_ESL_PASSWORD": ""
    }
  }
}
```

**Requires environment variables:** `ASTERISK_AMI_HOST`, `ASTERISK_AMI_PORT`, `ASTERISK_AMI_USERNAME`, `ASTERISK_AMI_PASSWORD`, `ASTERISK_AMI_TLS`, `FREESWITCH_ESL_HOST`, `FREESWITCH_ESL_PORT`, `FREESWITCH_ESL_PASSWORD` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What pbx-mcp MCP server does

The pbx-mcp MCP server gives an MCP-compatible assistant a common tool interface for two telephony platforms: Asterisk and FreeSWITCH. It connects to Asterisk using the Asterisk Manager Interface (AMI) and to FreeSWITCH using the Event Socket Layer (ESL). Configure either platform independently, or configure both in the same process.

For Asterisk, the available operations report software and call statistics, list active channels, inspect PJSIP endpoints or older `chan_sip` peers, and retrieve a complete dialplan context or a specific extension. An Asterisk CLI tool also accepts approved inspection commands. For FreeSWITCH, the tools report switch and session statistics, list live call legs, inspect Sofia registrations, and show SIP profiles and gateway registration state. Its API tool is similarly restricted to approved command prefixes.

Both platforms provide a preview operation for hangups. These previews identify the live channels or call legs that match a requested hangup without changing the PBX.

## How it works

The server communicates with the configured PBX over AMI or ESL and returns live results through MCP. Optional substring filters can narrow Asterisk channel results and FreeSWITCH channel results. Asterisk hangups target a channel name; FreeSWITCH hangups use a channel UUID. Originate and hangup operations are write actions rather than diagnostic queries.

Read-only mode is the starting state. The four write tools—origination and hangup for each platform—are not registered unless `PBX_MCP_ALLOW_WRITE=true`. Command tools use allow-listed inspection prefixes, and shell metacharacters are rejected before commands are sent. AMI action fields are also checked against header injection.

## Setup and configuration

Install with `npm install -g pbx-mcp` or run it with `npx -y pbx-mcp`. Node.js 18 or later is required. The server communicates over stdio, so it can be launched from an MCP client configuration or run in the provided container image with stdin attached. The container does not expose a listening port; the PBX must be reachable from inside the container.

Set `ASTERISK_AMI_HOST` to enable Asterisk support, along with the AMI username and password. The default AMI port is 5038, and AMI TLS can be enabled with `ASTERISK_AMI_TLS=true`. The AMI account needs read access to system, call, and command classes plus write access to command; originate permission is needed if call origination will be enabled.

Set `FREESWITCH_ESL_HOST` to enable FreeSWITCH support. ESL uses port 8021 by default and the documented default password is `ClueCon`, unless the switch configuration changes it. `PBX_MCP_TIMEOUT_MS` controls the per-command timeout and defaults to 10,000 milliseconds.

## Tools and capabilities

The pbx-mcp MCP server provides these capability groups:

- Asterisk status, channels, endpoints, dialplan, CLI inspection, hangup previews, origination, and hangup.
- FreeSWITCH status, channels, registrations, Sofia status, API inspection, hangup previews, origination, and hangup.
- Optional channel filtering for live-call listings.
- Explicit write-mode gating for actions that can place or terminate calls.

## Limitations and notes

The server depends on network access to the PBX and valid AMI or ESL credentials. It does not listen on a network port when used through stdio. Enabling write mode allows real call-control operations, including origination over a live trunk, so it should be enabled only with suitable credentials and operational safeguards. CLI and API access remains subject to their configured safety allow lists.

_Full upstream README: https://allmcps.com/mcp/pbx-mcp/readme_