Telephony MCP Server

1![Black](https://github.com/khan2a/telephony-mcp-server/actions/workflows/01-black.yml/badge.svg)
2![Ruff](https://github.com/khan2a/telephony-mcp-server/actions/workflows/02-ruff.yml/badge.svg)
3 
4 📖 **Blog Post**: Learn more about this project in the detailed blog post: [Telephony MCP Server for Agentic AI and Language Models](https://developer.vonage.com/en/blog/telephony-mcp-server-for-agentic-ai-and-language-models)
5 
6# Telephony MCP Server
7 
8## Demo Using Claude Desktop
9### Agentic Telephony Conversation with Speech Recognition
10<img src="./resources/demo-claude-agentic-call-speech-recognition.gif" alt="Agentic Telephony Conversation with Speech Recognition" style="border: 4px solid white; border-radius: 8px;"/>
11 
12### <span style="color: yellow;">Use SMS during mid-conversation</span>
13<img src="./resources/demo-claude-desktop.gif" alt="Telephony MCP Server Demo" style="border: 4px solid yellow; border-radius: 8px; display: block; margin-left: 0;"/>
14 
15### <span style="color: #b5651d;">SMS Enquiry (Send and Receive)</span>
16<img src="./resources/demo-claude-sms-enquiry.png" alt="SMS Enquiry" style="border: 4px solid #b5651d; border-radius: 8px; display: block; margin-left: 0;" width="800"/>
17 
18## <span style="color: green;">Demo Using GitHub Copilot</span>
19<img src="./resources/demo-copilot.gif" alt="Telephony MCP Server Demo" style="border: 4px solid green; border-radius: 8px; display: block; margin-left: 0;"/>
20 
21## Introduction
22 
23This directory contains MCP (Model Context Protocol) Server tools for telephony operations, such as making voice calls and sending SMS messages using the Vonage API. These tools are designed to be integrated with Large Language Model (LLM) applications, enabling LLMs to perform real-world actions beyond simple text generation.
24 
25## LLMs and Tool Integration
26 
27LLMs (Large Language Models) are advanced token generators—they can generate text, images, or even video based on input prompts. However, their core capability is limited to generating content; they cannot access external data or perform actions in the real world on their own.
28 
29To extend their functionality, LLMs can be connected to external tools. For example, when a user asks, "What's the weather today?" the LLM can invoke a backend API tool like `get_weather(city)` via a system prompt, parse the response, and return the result to the user. This tool-calling mechanism transforms a basic LLM into a powerful LLM Application.
30 
31## Tool Calling with MCP and LangChain
32 
33- **LangChain** is a popular framework for developing applications powered by LLMs. It provides a collection of pre-built tools (called a Toolkit) that LLMs can use to interact with external systems.
34- **MCP** (Model Context Protocol) follows the same concept: it offers a collection of pre-built tools and a framework for writing new tools and handling function calling.
35- Both frameworks allow LLMs to invoke tools, parse their outputs, and integrate the results into their responses.
36 
37## How This Works
38 
391. **Tool Definition**: In this project, tools like `voice_call` and `send_sms` are defined using the MCP framework. Each tool is a function that can be called by an LLM application.
402. **LLM Application**: When integrated with an LLM (such as OpenAI's GPT, Anthropic's Claude, etc.), the LLM can decide to call these tools based on user prompts.
413. **Execution Flow**:
42    - The LLM receives a prompt (e.g., "Call Alice and say hello").
43    - The LLM determines that a tool invocation is needed and calls the appropriate MCP tool (e.g., `voice_call`).
44    - The tool executes (e.g., initiates a phone call via Vonage) and returns the result.
45    - The LLM parses the response and presents it to the user.
46 
47## Running the MCP Tools
48 
49### Prerequisites
50 
51- Python 3.13+
52- MCP CLI (`mcp[cli]`), FastAPI, httpx, pyjwt, python-dotenv, uvicorn, pydantic (see `pyproject.toml` for details)
53- Vonage API credentials (API key, secret, application ID, private key)
54- Public URL for callback server (for production use)
55 
56### Setup
57 
581. **Install dependencies**:
59    ```bash
60    pip install -r requirements.txt
61    ```
62    Or, if using Poetry:
63    ```bash
64    poetry install
65    ```
66 
672. **Configure environment variables**:
68    - Create a `.env` file with your Vonage credentials:
69      ```
70      VONAGE_API_KEY=your_api_key
71      VONAGE_API_SECRET=your_api_secret
72      VONAGE_APPLICATION_ID=your_app_id
73      VONAGE_PRIVATE_KEY_PATH=path/to/private.key
74      VONAGE_LVN=your_virtual_number
75      VONAGE_API_URL=https://api.nexmo.com/v1/calls
76      VONAGE_SMS_URL=https://rest.nexmo.com/sms/json
77      CALLBACK_SERVER_URL=https://your-public-url  # URL for Vonage event callbacks
78      ```
79      
80      For the `CALLBACK_SERVER_URL`:
81      - In development: You can use `http://localhost:8080` (default if not specified)
82      - In production: Use a public URL (such as an ngrok URL or your deployed server)
83 
843. **Run the MCP server**:
85    ```bash
86    python telephony_server.py
87    ```
88    The server will start and expose the defined tools for LLM applications.
89 
90### Running with Docker
91 
92You can also run the telephony MCP server using Docker:
93 
941. **Build and start the Docker container**:
95    ```bash
96    docker compose up --build
97    ```
98    Or to run in the background:
99    ```bash
100    docker compose up --build -d
101    ```
102 
1032. **Stop the Docker container**:
104    ```bash
105    docker compose down
106    ```
107 
1083. **View logs from the Docker container**:
109    ```bash
110    docker compose logs -f
111    ```
112 
113### Using with LLM Applications
114 
115- **Direct Integration**: Connect your LLM application (e.g., using LangChain via Adapter or a custom MCP client) to the running MCP server. The LLM can now invoke telephony tools as needed.
116- **Example**: When the LLM receives a prompt like "Dial this number +123 and read latest news from today", it will call the `voice_call` tool, passing the required parameters.
117- **Example**: When the LLM receives a prompt like "Call this number using a British accent", it will call the `voice_call` tool with specific language and style parameters.
118- **Example**: When the LLM receives a prompt like "Text the news instead", it will call the `send_sms` tool, passing the required parameters.
119 
120### Using with Claude Desktop or other MCP clients
121 
122To configure an MCP client (like Claude Desktop) to use your telephony MCP server:
123 
1241. **Update your MCP client configuration file** (e.g., `claude_desktop_config.json`):
125    ```json
126    {
127      "mcpServers": {
128        "telephony": {
129          "command": "docker",
130          "args": ["run", "-i", "--rm", "--init", "-e", "DOCKER_CONTAINER=true", "telephony-mcp-server"]
131        }
132      }
133    }
134    ```
135 
1362. **Build the Docker image** (if not using docker compose):
137    ```bash
138    docker build -t telephony-mcp-server .
139    ```
140 
1413. Restart your MCP client to apply the changes.
142- 
143## Key Concepts
144 
145- **LLMs are content generators**: They generate text, images, or video, but need external tools for actions like web search, telephony, or database access.
146- **Tool calling**: LLMs can invoke backend APIs (tools) to fetch data or perform actions, then parse and present the results.
147- **Frameworks**: Both LangChain and MCP provide a structure for defining, registering, and invoking tools from LLMs.
148- **MCP**: Helps you write new tools and manage function calling, making it easy to extend LLM applications with custom capabilities.
149 
150## Callback Server for Vonage Events
151 
152The Telephony MCP Server also includes a Vonage Callback Server that listens on port 8080. This server is used to receive event notifications from Vonage Voice API, which are sent when voice calls are initiated, completed, or encounter errors.
153 
154### Features
155- Receives and stores Vonage event callbacks
156- Provides endpoints to view and manage stored events
157- Runs as a separate service within the same application
158 
159### Endpoints
160- `GET /` - Health check endpoint
161- `POST /event` - Main endpoint for receiving Vonage callbacks
162- `GET /events` - List all stored events (with pagination)
163- `GET /events/{event_id}` - Get a specific event by ID
164- `DELETE /events` - Clear all stored events
165 
166### Configuration
167To use the callback server with Vonage Voice API, you need to set the `CALLBACK_SERVER_URL` environment variable to your server's public URL. This URL will be used as the `event_url` parameter in Vonage API calls.
168 
169```bash
170export CALLBACK_SERVER_URL="https://your-public-url"
171```
172 
173For local development, you can use a service like ngrok to expose your local server to the internet:
174 
175```bash
176ngrok http 8080
177```
178 
179Then set the `CALLBACK_SERVER_URL` to the ngrok URL.
180