# Pbx MCP

> Pbx MCP is a free MCP server for communication. Inspect and control Asterisk and FreeSWITCH PBX servers from an AI assistant. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Free
- **Platforms:** CLI, self-hosted, Linux
- **Website:** https://ictinnovations.com
- **Repository:** https://github.com/ictinnovations/pbx-mcp
- **MCP Registry name:** io.github.ictinnovations/pbx-mcp
- **Categories:** communication, cloud and infrastructure
- **Listing updated:** 2026-11-15

## About

The idea is to answer questions like which extensions are offline or why a SIP trunk won't register from the live switch. Asterisk is reached through AMI and FreeSWITCH through ESL, and the server only registers tools for the side you configure, so an Asterisk-only shop never sees FreeSWITCH tools.

There are twelve read-only tools, six per engine. Four write tools, asterisk_originate, asterisk_hangup, freeswitch_originate and freeswitch_hangup, stay hidden until PBX_MCP_ALLOW_WRITE=true, because placing a call on a live trunk costs real money. The Asterisk manager user needs read access to system, call and command, plus write for command.

It runs from npm (Node 18 or newer) or a prebuilt non-root Docker image; use -i, since it speaks MCP over stdio and publishes no port. ICT Innovations built it.

## Features

- **Dual engine:** Asterisk AMI and FreeSWITCH ESL behind one tool set.
- **Twelve read tools:** Six per engine for inspection.
- **Gated call control:** Originate and hangup tools appear only with PBX_MCP_ALLOW_WRITE.
- **Configure what you use:** Tools register only for the configured switch.
- **Docker image:** Non-root image available on GHCR and Docker Hub.

## Good for

- Find offline extensions
- Diagnose a SIP trunk registration failure
- Check active calls
- Run the same questions on mixed Asterisk and FreeSWITCH setups

## Install

### Claude Code (Terminal)

```sh
claude mcp add pbx-mcp --env ASTERISK_AMI_PASSWORD='<ASTERISK_AMI_PASSWORD>' --env FREESWITCH_ESL_PASSWORD='<FREESWITCH_ESL_PASSWORD>' -- npx -y pbx-mcp
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "pbx-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "pbx-mcp"
      ],
      "env": {
        "ASTERISK_AMI_PASSWORD": "<ASTERISK_AMI_PASSWORD>",
        "FREESWITCH_ESL_PASSWORD": "<FREESWITCH_ESL_PASSWORD>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "pbx-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "pbx-mcp"
      ],
      "env": {
        "ASTERISK_AMI_PASSWORD": "<ASTERISK_AMI_PASSWORD>",
        "FREESWITCH_ESL_PASSWORD": "<FREESWITCH_ESL_PASSWORD>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "pbx-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "pbx-mcp"
      ],
      "env": {
        "ASTERISK_AMI_PASSWORD": "<ASTERISK_AMI_PASSWORD>",
        "FREESWITCH_ESL_PASSWORD": "<FREESWITCH_ESL_PASSWORD>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "pbx-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "pbx-mcp"
      ],
      "env": {
        "ASTERISK_AMI_PASSWORD": "<ASTERISK_AMI_PASSWORD>",
        "FREESWITCH_ESL_PASSWORD": "<FREESWITCH_ESL_PASSWORD>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "pbx-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "pbx-mcp"
      ],
      "env": {
        "ASTERISK_AMI_PASSWORD": "<ASTERISK_AMI_PASSWORD>",
        "FREESWITCH_ESL_PASSWORD": "<FREESWITCH_ESL_PASSWORD>"
      }
    }
  }
}
```

## Tools

- `asterisk_originate`: Places a call through Asterisk; only with write mode.
- `asterisk_hangup`: Ends a call on Asterisk; only with write mode.
- `freeswitch_originate`: Places a call through FreeSWITCH; only with write mode.
- `freeswitch_hangup`: Ends a call on FreeSWITCH; only with write mode.

## FAQ

### Can it place calls?

Only after setting PBX_MCP_ALLOW_WRITE=true.

### Does it need both Asterisk and FreeSWITCH?

No, set either or both.

### What Node version?

18 or newer.

### Why is -i needed in Docker?

The server uses stdio and needs stdin attached.

### Is Pbx MCP free?

Yes. Pbx MCP is free to use.

### How do I add Pbx MCP to Claude Code?

Run this command in your terminal: claude mcp add pbx-mcp --env ASTERISK_AMI_PASSWORD='<ASTERISK_AMI_PASSWORD>' --env FREESWITCH_ESL_PASSWORD='<FREESWITCH_ESL_PASSWORD>' -- npx -y pbx-mcp

### What are the best alternatives to Pbx MCP?

The closest alternatives to Pbx MCP are BoardAgent, Callout, nicemails, SOMMON Office and PostBaton.

## Alternatives

- [BoardAgent](https://ai-powered.com/mcp/boardagent): BoardAgent is a free MCP server for community directories.
- [Callout](https://ai-powered.com/mcp/callout): Callout is a freemium MCP server for communication.
- [nicemails](https://ai-powered.com/mcp/nicemails): nicemails is a freemium MCP server for communication.
- [SOMMON Office](https://ai-powered.com/mcp/sommon-office): SOMMON Office is a paid MCP server for communication.
- [PostBaton](https://ai-powered.com/mcp/postbaton): PostBaton is a freemium MCP server for marketing and seo.
- [MeetBetr](https://ai-powered.com/mcp/meetbetr): MeetBetr is a free MCP server for productivity.
- [Agent Yurt](https://ai-powered.com/mcp/agent-yurt): Agent Yurt is a free MCP server for knowledge and memory.
- [Host Tools](https://ai-powered.com/mcp/host-tools): Host Tools is an MCP server for home services.

---
Source: https://ai-powered.com/mcp/pbx-mcp
