# pbx-mcp

Lets an AI assistant query a live Asterisk or FreeSWITCH PBX: active channels, endpoints, dialplan and trunk registration.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 19
- Author: ictinnovations
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/ictinnovations/pbx-mcp
- Updated: 2026-10-09
- HTML: https://affpapa.org/en/nevibecode/mcp/pbx-mcp

## What it 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.

## Requirements
- Needs: Node.js (commands run via npx)
- 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`, `PBX_MCP_ALLOW_WRITE`, `PBX_MCP_TIMEOUT_MS` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
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-mcp
```
Replace <…> with your own values. 5 more environment variables are in the server README

### Codex

**Platform CLI**
```bash
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-mcp
```
Replace <…> with your own values. 5 more environment variables are in the server README

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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

### Gemini CLI

**Platform CLI**
```bash
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-mcp
```
Replace <…> with your own values. 5 more environment variables are in the server README

## When to use it
- 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
- 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`

## Similar
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [Oh My Posh Validator](https://affpapa.org/en/nevibecode/mcp/oh-my-posh-validator.md) — MCP server · ★ 23643
- [Keploy](https://affpapa.org/en/nevibecode/mcp/keploy.md) — MCP server · ★ 18727
- [Coder](https://affpapa.org/en/nevibecode/mcp/coder.md) — MCP server · ★ 17160
- [mcp](https://affpapa.org/en/nevibecode/mcp/kubeshark-mcp.md) — MCP server · ★ 12109

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md