Skip to main content
Glama

Asterisk S2S MCP Server

by gcorroto
README.mdβ€’8.49 kB
# 🌟 Asterisk S2S MCP Server <div align="center"> ![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg) ![TypeScript](https://img.shields.io/badge/TypeScript-5.6+-blue.svg) ![MCP](https://img.shields.io/badge/MCP-1.6.1-purple.svg) ![License](https://img.shields.io/badge/License-MIT-yellow.svg) ![NPM](https://img.shields.io/badge/NPM-Latest-red.svg) **πŸš€ MCP Server for automated conversational phone calls using Asterisk with Speech-to-Speech** *Make phone conversations as easy as a prompt!* πŸ“žβœ¨ </div> --- ## πŸ—οΈ System Architecture ```mermaid 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 ``` --- ## πŸ“ž Phone Call Flow ```mermaid 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 ```mermaid 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) ```bash # One command and you're ready! πŸš€ npx @grec0/mcp-s2s-asterisk@latest ``` ### πŸ”§ Option 2: Global Installation ```bash npm install -g @grec0/mcp-s2s-asterisk mcp-s2s-asterisk ``` --- ## βš™οΈ Step-by-Step Configuration ```mermaid 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 ```bash # 🌐 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 ```json { "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 <table> <tr> <td width="50%"> ### πŸ“ž **Calls** - πŸ”₯ `phone_make_call` - Make phone calls - πŸ“Š `phone_get_status` - Get call status - ❌ `phone_cancel_call` - Cancel calls - πŸ“± `phone_get_active_calls` - Active calls </td> <td width="50%"> ### πŸ“ˆ **Monitoring** - ❀️ `phone_health_check` - System health - πŸ“Š `phone_get_metrics` - Advanced metrics - πŸ“ `phone_get_logs` - Detailed logs - πŸ—‚οΈ `phone_get_conversation_history` - History </td> </tr> </table> --- ## πŸ’‘ Use Cases ```mermaid graph LR subgraph "Automation" A[Appointment<br/>Reminders] B[Booking<br/>Confirmations] C[Automated<br/>Surveys] end subgraph "Support" D[Customer<br/>Service] E[Ticket<br/>Follow-up] F[Data<br/>Verification] end subgraph "Sales" G[Automated<br/>Prospecting] H[Lead<br/>Follow-up] I[Customer<br/>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 ```mermaid 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<br/>Speech-to-Speech note right of Completed : Result processed<br/>and saved ``` --- ## πŸ“– Complete Usage Example ### 🎬 Scenario: Medical Appointment Confirmation ```typescript // 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 ```mermaid pie title Call Distribution by Status "Completed" : 65 "In Progress" : 15 "Failed" : 12 "Cancelled" : 8 ``` ```mermaid 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 ```bash # πŸ“₯ 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 ```mermaid 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 <div align="center"> Do you like the project? We'd love your contribution! [![GitHub](https://img.shields.io/badge/GitHub-Contribute-black?style=for-the-badge&logo=github)](https://github.com/grec0/mcp-s2s-asterisk) [![Issues](https://img.shields.io/badge/Issues-Report-red?style=for-the-badge&logo=github)](https://github.com/grec0/mcp-s2s-asterisk/issues) [![Pull Requests](https://img.shields.io/badge/PRs-Welcome-green?style=for-the-badge&logo=github)](https://github.com/grec0/mcp-s2s-asterisk/pulls) </div> --- ## πŸ“„ License <div align="center"> **MIT License** - Use it, modify it, distribute it freely [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT) </div> --- <div align="center"> ### 🌟 Give it a star if you like the project! ⭐ **Made with ❀️ by [@grec0](https://github.com/grec0)** *Transforming phone communication with conversational AI* </div>

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/gcorroto/mcp-s2s-asterisk'

If you have feedback or need assistance with the MCP directory API, please join our Discord server