What is Asterisk Bot Mcp

Asterisk-bot-mcp is a TypeScript Node.js server designed as a Management Control Program (MCP) for Asterisk servers, enabling interaction and management functionalities.

Use cases

Use cases include managing VoIP systems, automating call routing, monitoring call statuses, and integrating Asterisk with other applications or services.

How to use

To use asterisk-bot-mcp, clone the repository, install dependencies using ‘npm install’, configure environment variables in the .env file with your Asterisk AMI credentials, and run the server.

Key features

Key features include checking PJSIP endpoint registration status, creating and managing extensions, configuring ring groups, setting up call queues, modifying dialplan logic, and real-time call monitoring.

Where to use

Asterisk-bot-mcp can be used in telecommunications, VoIP services, and any environment requiring management of Asterisk servers.

Asterisk Bot MCP Server

This project is a TypeScript Node.js server designed to act as a Management Control Program (MCP) for an Asterisk server. It provides functionalities to interact with Asterisk.

Proof of Concept (POC) - Phase 1:
The initial version primarily focuses on a proof-of-concept command: checking PJSIP endpoint registration status. This serves as the first round of testing and establishes the foundational connection and interaction with Asterisk.

Future Vision:
The long-term goal is to develop this into a full-fledged MCP server. This advanced server will enable comprehensive control and management of an Asterisk instance, potentially through an interface suitable for interaction with Large Language Models (LLMs) like Claude. Planned capabilities include, but are not limited to:

• Creating and managing extensions (PJSIP and SIP)
• Configuring ring groups
• Setting up and managing call queues
• Modifying dialplan logic
• Real-time call monitoring and control
• And much more, providing a robust API for programmatic Asterisk administration.

This project aims to simplify complex Asterisk management tasks through a modern, programmatic interface.

Prerequisites

• Node.js (v16 or later recommended)
• npm (usually comes with Node.js)
• An Asterisk server with AMI (Asterisk Manager Interface) enabled and configured.
  • For local development, you can run Asterisk in Docker, WSL, or a VM.

Setup

1. Clone the repository (if applicable) or ensure all files are in your project directory.

2. Install dependencies:

   npm install
   

3. Configure Environment Variables:

   • Copy the .env.example file to a new file named .env:

     # On Windows (PowerShell)
     Copy-Item .env.example .env
     # On macOS/Linux
     # cp .env.example .env
     

   • Edit the .env file with your Asterisk AMI credentials:

     ASTERISK_HOST=your_asterisk_ip_or_hostname
     ASTERISK_PORT=your_ami_port (default: 5038)
     ASTERISK_USERNAME=your_ami_username
     ASTERISK_SECRET=your_ami_secret
     

     Ensure your Asterisk manager.conf allows this user to connect from the host where this MCP server will run and has necessary read/write permissions (e.g., system, call, config, reporting depending on future needs. For PJSIPShowEndpoints, system or config read permissions are typically needed).

Available Scripts

• Build the project:

  npm run build
  

  This compiles TypeScript to JavaScript in the dist directory.

• Start the server (production mode):

  npm run start
  

  This runs the compiled code from the dist directory.

• Start the server (development mode):

  npm run dev
  

  This uses nodemon and ts-node to run the server and automatically restart it on file changes in the src directory.

• Lint the code:

  npm run lint
  

  This checks the code for linting errors using ESLint.

• Format the code:

  npm run format
  

  This formats the code using Prettier.

• Run tests:

  npm run test
  

  This executes tests using Jest.

• Check PJSIP Registered Endpoints:

  npm run check-endpoints
  

  This script connects to the Asterisk server defined in your .env file, queries for PJSIP endpoints, and reports how many are currently considered registered.

  Note: This check-endpoints script is part of the initial proof-of-concept phase.

Asterisk Configuration Notes (manager.conf)

Ensure your Asterisk manager.conf has a user configured with appropriate permissions. For example:

[mcp_user] ; Corresponds to ASTERISK_USERNAME
secret = your_ami_secret ; Corresponds to ASTERISK_SECRET
permit = 0.0.0.0/0 ; Or a more specific IP/subnet for security
read = system,call,log,verbose,command,agent,user,config,dtmf,reporting,cdr,dialplan,originate
write = system,call,log,verbose,command,agent,user,config,dtmf,reporting,cdr,dialplan,originate
; Adjust read/write permissions as needed. For PJSIPShowEndpoints, 'system' or 'config' read is usually sufficient.

Reload Asterisk dialplan or manager settings after changes (manager reload in Asterisk CLI).