Asterisk S2S MCP Server
by gcorroto
README.md
# 🌟 Asterisk S2S MCP Server
<div align="center">
**🚀 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!
[](https://github.com/grec0/mcp-s2s-asterisk)
[](https://github.com/grec0/mcp-s2s-asterisk/issues)
[](https://github.com/grec0/mcp-s2s-asterisk/pulls)
</div>
---
## 📄 License
<div align="center">
**MIT License** - Use it, modify it, distribute it freely
[](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> TDQS
A3.6/5.0
Scored across 9 tools
Disambiguation5/5
Every tool has a clearly distinct purpose with no ambiguity. Each tool targets a specific action (cancel, get, make, check) on specific telephone system resources (calls, history, logs, metrics, status, health), making it easy for an agent to select the right tool without confusion.
Naming Consistency5/5
All tools follow a perfect verb_noun pattern with consistent snake_case naming. The 'phone_' prefix establishes clear domain ownership, and action verbs (cancel, get, make, check) are consistently applied throughout the set.
Tool Count5/5
Nine tools is an excellent number for a telephone system server. This provides comprehensive coverage without being overwhelming, allowing agents to handle all major telephone operations while maintaining manageable cognitive load.
Completeness5/5
The tool set provides complete lifecycle coverage for telephone operations: initiating calls (make_call), monitoring active calls and status, accessing history and results, canceling calls, checking system health, and gathering logs and metrics. No obvious gaps exist for the stated telephone system domain.
Maintenance
ActivityInactive
ResponsivenessNo issues