Skip to content
MCP server

Pbx MCP

Inspect and control Asterisk and FreeSWITCH PBX servers from an AI assistant

Runs locallyStatus and history
Pricing
Free
Platforms
CLI, self-hosted, Linux
Runs
Locally
Version
0.1.4
Listing updated
2 days ago

About Pbx MCP

Pbx MCP is a free MCP server for communication. It runs locally on your machine and is started by your AI client.

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.

Install

Run in a terminal

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

Add to claude_desktop_config.json

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

Add to ~/.cursor/mcp.json

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

Add to .vscode/mcp.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>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

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

Add to your client's MCP settings (most use this shape)

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

Configuration

  • ASTERISK_AMI_HOSTHostname or IP of the Asterisk server. Set this to enable the Asterisk tools.
  • ASTERISK_AMI_PORTAsterisk Manager Interface port. Defaults to 5038.
  • ASTERISK_AMI_USERNAMEAMI username from manager.conf.
  • ASTERISK_AMI_PASSWORDAMI secret from manager.conf.
  • ASTERISK_AMI_TLSConnect to AMI over TLS. Set true if tlsenable=yes in manager.conf.
  • FREESWITCH_ESL_HOSTHostname or IP of the FreeSWITCH server. Set this to enable the FreeSWITCH tools.
  • FREESWITCH_ESL_PORTFreeSWITCH inbound event socket port. Defaults to 8021.
  • FREESWITCH_ESL_PASSWORDEvent socket password from event_socket.conf.xml. Defaults to ClueCon, which you should change.
  • PBX_MCP_ALLOW_WRITEUnlocks call control. When false the server is read-only and the originate and hangup tools are not registered at all. Placing a call on a live trunk costs real money, so leave this off unless you mean it.
  • PBX_MCP_TIMEOUT_MSPer command timeout in milliseconds. Defaults to 10000.

Tools this server provides (4)

Taken from the project documentation; the running server may differ.

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.

What it does

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

Pricing

Free

Prices change. Check ictinnovations.com before you buy.

Pbx MCP 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 to Pbx MCP

  1. BoardAgent

    MCP server

    Remote MCP server for a message board where only AI agents post, reply and vote

    • 27 tools
    • Remote
    • Free
    • Community directories
  2. Callout

    MCP server

    Let an AI agent place real phone calls in Japanese or English and read the transcript

    • 5 tools
    • Remote
    • Freemium
    • Communication
  3. nicemails

    MCP server

    Give each AI agent its own real mailbox to read, search and send email with your approval

    • 8 tools
    • Remote
    • Freemium
    • Communication
  4. SOMMON Office

    MCP server

    Send real paper letters via Deutsche Post from an AI assistant, to 218 countries

    Not checked yet
    • 14 tools
    • Remote
    • Paid
    • Communication
  5. PostBaton

    MCP server

    Schedule, edit and cancel social posts across networks from an AI assistant or REST API

    Not checked yet
    • Remote
    • Freemium
    • Marketing and SEO
  6. MeetBetr

    MCP server

    Find when friends are free and send them a plan after you confirm it

    • Remote
    • Free
    • Productivity