🌟 Asterisk S2S MCP Server

Node.js TypeScript MCP License NPM

🚀 MCP Server for automated conversational phone calls using Asterisk with Speech-to-Speech

Make phone conversations as easy as a prompt! 📞✨

🏗️ System Architecture

graph TB subgraph "MCP Client" A[Claude Desktop] --> B[MCP Client] end subgraph "MCP Server" B --> C[Asterisk S2S MCP] C --> D[Phone Tools] C --> E[Real-time Assistant] end subgraph "Backend Services" D --> F[Asterisk Server] E --> G[Speech-to-Speech API] F --> H[Phone Network] end subgraph "Monitoring" C --> I[Health Check] C --> J[Metrics & Logs] C --> K[Call History] end style A fill:#e1f5fe style C fill:#f3e5f5 style F fill:#fff3e0 style G fill:#e8f5e8

Related MCP server: Fonoster MCP Server

📞 Phone Call Flow

sequenceDiagram participant U as User participant C as Claude/MCP participant S as MCP Server participant A as Asterisk API participant P as Phone U->>C: "Call John to remind about appointment" C->>S: phone_make_call() S->>A: POST /make-call A->>P: Initiate call P-->>A: Connection established A-->>S: CallID + Status S-->>C: Call initiated ✅ C-->>U: "📞 Call started with John" Note over A,P: Real-time S2S conversation A->>S: Callback with result S->>S: Process transcript U->>C: "How did the call go?" C->>S: phone_get_last_result() S-->>C: Detailed result C-->>U: "✅ John confirmed the appointment"

🛠️ MCP Components

mindmap root((Asterisk S2S MCP)) Core Tools phone_make_call phone_get_status phone_cancel_call Monitoring phone_health_check phone_get_metrics phone_get_logs History phone_get_conversation_history phone_get_active_calls phone_get_last_result Configuration Environment Variables MCP Client Config Asterisk Integration

🚀 Installation & Usage

🎯 Option 1: NPX (Recommended)

# One command and you're ready! 🚀 npx @grec0/mcp-s2s-asterisk@latest

🔧 Option 2: Global Installation

npm install -g @grec0/mcp-s2s-asterisk mcp-s2s-asterisk

⚙️ Step-by-Step Configuration

flowchart LR A[1. Install MCP] --> B[2. Configure Variables] B --> C[3. Configure MCP Client] C --> D[4. Ready to use! 🎉] style A fill:#ffcdd2 style B fill:#fff3e0 style C fill:#e8f5e8 style D fill:#e1f5fe

🔐 Environment Variables

# 🌐 Asterisk API URL export PHONE_API_URL="http://192.168.4.44:8000" # 🔑 Authentication key export PHONE_API_KEY="api-key" # 🔄 Callback URL for results export MCP_CALLBACK_URL="http://localhost:3000"

📱 MCP Client Configuration

{ "mcpServers": { "asterisk-s2s": { "command": "npx", "args": ["@grec0/mcp-s2s-asterisk@latest"], "env": { "PHONE_API_URL": "http://192.168.4.44:8000", "PHONE_API_KEY": "api-key", "MCP_CALLBACK_URL": "http://localhost:3000" } } } }

🧰 Available Tools

📞 Calls

🔥 phone_make_call - Make phone calls
📊 phone_get_status - Get call status
❌ phone_cancel_call - Cancel calls
📱 phone_get_active_calls - Active calls

📈 Monitoring

❤️ phone_health_check - System health
📊 phone_get_metrics - Advanced metrics
📝 phone_get_logs - Detailed logs
🗂️ phone_get_conversation_history - History

💡 Use Cases

graph LR subgraph "Automation" A[Appointment Reminders] B[Booking Confirmations] C[Automated Surveys] end subgraph "Support" D[Customer Service] E[Ticket Follow-up] F[Data Verification] end subgraph "Sales" G[Automated Prospecting] H[Lead Follow-up] I[Customer Qualification] end style A fill:#ffcdd2 style B fill:#f8bbd9 style C fill:#e1bee7 style D fill:#c5cae9 style E fill:#bbdefb style F fill:#b3e5fc style G fill:#b2dfdb style H fill:#c8e6c9 style I fill:#dcedc8

🔄 Call States

stateDiagram-v2 [*] --> Starting Starting --> Connecting: API Request Connecting --> Speaking: Connection OK Connecting --> Failed: No answer Speaking --> Completed: Conversation OK Speaking --> Cancelled: User Cancel Completed --> [*] Failed --> [*] Cancelled --> [*] note right of Speaking : Real-time Speech-to-Speech note right of Completed : Result processed and saved

📖 Complete Usage Example

🎬 Scenario: Medical Appointment Confirmation

// 1️⃣ User tells Claude: "Call María González at 555-0123 to confirm her appointment tomorrow at 3pm" // 2️⃣ Claude automatically uses: phone_make_call({ usuario: "María González", telefono: "555-0123", proposito: "Confirm medical appointment for tomorrow 3pm", timeout: 60 }) // 3️⃣ Automatic result: "✅ Call completed. María confirmed her appointment for tomorrow at 3pm. She also asked to change the time to 2:30pm if possible."

🚦 Monitoring Dashboard

pie title Call Distribution by Status "Completed" : 65 "In Progress" : 15 "Failed" : 12 "Cancelled" : 8

xychart-beta title "Daily Calls (Last Week)" x-axis [Mon, Tue, Wed, Thu, Fri, Sat, Sun] y-axis "Number of Calls" 0 --> 50 bar [23, 34, 28, 41, 38, 15, 8]

🔧 Local Development

📋 Requirements

🟢 Node.js >= 18.0.0
📦 npm or pnpm
🔧 TypeScript

🛠️ Quick Setup

# 📥 Clone repository git clone <repository-url> cd mcp-s2s-asterisk # 📦 Install dependencies npm install # 🔨 Build project npm run build # 🚀 Run server npm run start

📋 Available Scripts

Script	Description	Command
🔨	Compile TypeScript	`npm run build`
👀	Development mode	`npm run dev`
🧪	Run tests	`npm run test`
🔍	MCP Inspector	`npm run inspector`
📦	Release patch	`npm run release:patch`

📊 Performance Metrics

graph TB subgraph "Response Time" A[Connection: ~2s] B[Establishment: ~3s] C[Conversation: Variable] D[Processing: ~1s] end subgraph "Success Rates" E[Connection: 95%] F[Completed: 87%] G[Satisfaction: 92%] end style E fill:#c8e6c9 style F fill:#c8e6c9 style G fill:#c8e6c9

🔒 Security & Compliance

🔐 Authentication: Mandatory API Key
🛡️ Encryption: TLS/SSL in transit
📝 Logs: Complete call auditing
🔒 Privacy: Locally processed data
✅ GDPR: Privacy compliance

🤝 Contributing

Do you like the project? We'd love your contribution!

📄 License

MIT License - Use it, modify it, distribute it freely

🌟 Give it a star if you like the project! ⭐

Made with ❤️ by

Transforming phone communication with conversational AI

Asterisk S2S MCP Server