telephony

The Telephony MCP Server exposes tools for performing real-world telephony actions such as making voice calls and sending SMS messages via the Vonage API. This enables LLM-powered applications to extend their capabilities beyond text generation by invoking these tools to interact with the real world (e.g., placing calls or sending updates via SMS) as part of a larger workflow. The server is designed to integrate with MCP-compatible clients (like LangChain adapters or Claude Desktop) so that prompts can trigger tool calls like voice_call and send_sms and then relay results back to the user. Additionally, the server includes a Vonage Callback Server that receives event notifications for call status and other events, which you can query or view to monitor activity.

Prerequisites:

• Python 3.13+ installed on your system
• MCP CLI and dependencies (e.g., mcp[cli], FastAPI, httpx, pyjwt, python-dotenv, uvicorn, pydantic) as described in the project setup
• Vonage API credentials (API key, API secret, Application ID, Private Key)
• A publicly accessible callback URL for Vonage event notifications (or a tunneling solution for development)

Install steps:

1. Clone the repository and navigate to the Telephony MCP server folder.
2. Create a Python virtual environment (optional but recommended):

   python -m venv venv
   source venv/bin/activate  # on macOS/Linux
   .\venv\Scripts\activate   # on Windows
   

3. Install dependencies:

   pip install -r requirements.txt
   

   Or, if using Poetry:

   poetry install
   

4. Configure environment variables (example):
   • Create a .env file with your Vonage credentials and callback URL as shown in the README.
5. Run the MCP server:

   python telephony_server.py
   

6. Optional: Run with Docker (if you prefer containerized deployment):

   docker compose up --build
   

Tips and tips:

• Ensure your Vonage credentials are correct and that your application is configured to accept callbacks at the public URL specified in CALLBACK_SERVER_URL.
• For local development, you can use a tunneling service to expose your local callback server (e.g., ngrok) and set CALLBACK_SERVER_URL accordingly.
• The Vonage Callback Server listens on port 8080; ensure that port is accessible if deploying behind a firewall.
• If you change environment variables (e.g., API URL or LVN), restart the MCP server to apply changes.
• When integrating with LLMs, expose tool names like voice_call and send_sms and ensure the input prompts map to the required parameters for each tool.
• If you use the Claude Desktop integration example, you can configure your MCP client to run the telephony server inside a docker container using a suitable mcpServers entry.
• Monitor logs via docker compose logs -f or your local run to troubleshoot issues with authentication, callback delivery, or network access.