khan2a/telephony-mcp-server

Telephony MCP Server
Demo Using Claude Desktop
Agentic Telephony Conversation with Speech Recognition
Use SMS during mid-conversation
SMS Enquiry (Send and Receive)
Demo Using GitHub Copilot
Introduction
This 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.
LLMs and Tool Integration
LLMs (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.
To 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.
Tool Calling with MCP and LangChain
- **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.
- **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.
- Both frameworks allow LLMs to invoke tools, parse their outputs, and integrate the results into their responses.
How This Works
1. **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.
2. **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.
3. **Execution Flow**:
- The LLM receives a prompt (e.g., "Call Alice and say hello").
- The LLM determines that a tool invocation is needed and calls the appropriate MCP tool (e.g., voice_call).
- The tool executes (e.g., initiates a phone call via Vonage) and returns the result.
- The LLM parses the response and presents it to the user.
Running the MCP Tools
Prerequisites
- Python 3.13+
- MCP CLI (mcp[cli]), FastAPI, httpx, pyjwt, python-dotenv, uvicorn, pydantic (see pyproject.toml for details)
- Vonage API credentials (API key, secret, application ID, private key)
- Public URL for callback server (for production use)
Setup
1. **Install dependencies**:
Or, if using Poetry:
2. **Configure environment variables**:
- Create a .env file with your Vonage credentials:
For the CALLBACK_SERVER_URL:
- In development: You can use http://localhost:8080 (default if not specified)
- In production: Use a public URL (such as an ngrok URL or your deployed server)
3. **Run the MCP server**:
The server will start and expose the defined tools for LLM applications.
Running with Docker
You can also run the telephony MCP server using Docker: