Telephony MCP Server
About
Make voice calls and send SMS messages using the Vonage API.
Details
- Author
- khan2a
- Categories
- Communication, Other, API
Jump to
Setup
Install Telephony MCP Server in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/khan2a/telephony-mcp-server
Follow the installation instructions in the repository README, then restart your MCP client.
Make voice calls and send SMS messages using the Vonage API.
📖Blog Post: Learn more about this project in the detailed blog post:Telephony MCP Server for Agentic AI and Language Models
Agentic Telephony Conversation with Speech Recognition
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 (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 likeget_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.
- LangChainis 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.
- Tool Definition: In this project, tools likevoice_callandsend_smsare defined using the MCP framework. Each tool is a function that can be called by an LLM application.
- 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.
- 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.
- Python 3.13+
- MCP CLI (mcp[cli]), FastAPI, httpx, pyjwt, python-dotenv, uvicorn, pydantic (seepyproject.tomlfor details)
- Vonage API credentials (API key, secret, application ID, private key)
- Public URL for callback server (for production use)
-
Create a.envfile with your Vonage credentials:
VONAGE_API_KEY=your_api_key VONAGE_API_SECRET=your_api_secret VONAGE_APPLICATION_ID=your_app_id VONAGE_PRIVATE_KEY_PATH=path/to/private.key VONAGE_LVN=your_virtual_number VONAGE_API_URL=https://api.nexmo.com/v1/calls VONAGE_SMS_URL=https://rest.nexmo.com/sms/json CALLBACK_SERVER_URL=https://your-public-url # URL for Vonage event callbacks
- In development: You can usehttp://localhost:8080(default if not specified)
- In production: Use a public URL (such as an ngrok URL or your deployed server)
The server will start and expose the defined tools for LLM applications.
You can also run the telephony MCP server using Docker:
- 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.
- Example: When the LLM receives a prompt like "Dial this number +123 and read latest news from today", it will call thevoice_calltool, passing the required parameters.
- Example: When the LLM receives a prompt like "Call this number using a British accent", it will call thevoice_calltool with specific language and style parameters.
- Example: When the LLM receives a prompt like "Text the news instead", it will call thesend_smstool, passing the required parameters.
Using with Claude Desktop or other MCP clients
To configure an MCP client (like Claude Desktop) to use your telephony MCP server:
-
Update your MCP client configuration file(e.g.,claude_desktop_config.json):
{ "mcpServers": { "telephony": { "command": "docker", "args": ["run", "-i", "--rm", "--init", "-e", "DOCKER_CONTAINER=true", "telephony-mcp-server"] } } }
Build the Docker image(if not using docker compose):
Restart your MCP client to apply the changes.
- LLMs are content generators: They generate text, images, or video, but need external tools for actions like web search, telephony, or database access.
- Tool calling: LLMs can invoke backend APIs (tools) to fetch data or perform actions, then parse and present the results.
- Frameworks: Both LangChain and MCP provide a structure for defining, registering, and invoking tools from LLMs.
- MCP: Helps you write new tools and manage function calling, making it easy to extend LLM applications with custom capabilities.
The 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.
- Receives and stores Vonage event callbacks
- Provides endpoints to view and manage stored events
- Runs as a separate service within the same application
- GET /- Health check endpoint
- POST /event- Main endpoint for receiving Vonage callbacks
- GET /events- List all stored events (with pagination)
- GET /events/{event_id}- Get a specific event by ID
- DELETE /events- Clear all stored events
To use the callback server with Vonage Voice API, you need to set theCALLBACK_SERVER_URLenvironment variable to your server's public URL. This URL will be used as theevent_urlparameter in Vonage API calls.
export CALLBACK_SERVER_URL="https://your-public-url"
For local development, you can use a service like ngrok to expose your local server to the internet:
Then set theCALLBACK_SERVER_URLto the ngrok URL.
Enables seamless integration with communication platform that allows you to reach your customers globally across any channel.
Platfone - Receive SMS & Virtual Numbers MCP
Virtual phone number platform for AI agents — rent numbers across 200+ countries, receive SMS, and manage the full activation lifecycle
Wavix is a global communications platform offering APIs for voice, SMS, 2FA, and phone numbers. Our MCP server brings these capabilities to AI agents and agentic workflows.
Self-hosted email and SMS platform for AI agents — each agent gets a real email address, phone number, inbox, and API key.
Send SMS messages using the Aligo SMS API.
A read-only MCP server for querying live Twilio data, powered by the CData JDBC Driver.
Send SMS, query delivery reports, manage senders / blacklists, register and check İYS (Turkish messaging consent registry) records through the iletiMerkezi BTK-licensed SMS API. 11 tools, runtime-fetched manifest stays in lock-step with the live API. Install: npx -y @iletimerkezi/mcp-server
A public MCP server that gives AI agents access to real UK carrier phone numbers for SMS verification. Agents can rent disposable or rental numbers, pay Lightning invoices, and read incoming SMS, all through standard MCP tool calls with no authentication required.
Get virtual phone numbers for SMS verification, OTP receipt, and number management.
Make voice calls and send SMS messages using the Vonage API.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
