📬 WhatsApp-MCP: Streamable Messaging Server

A powerful, event-stream-based WhatsApp messaging server built with FastMCP and Twilio API.
Send messages programmatically or from a browser using Server-Sent Events — perfect for agents, automation, or dashboards.

---

🛠 Features

• ✅ FastMCP 2.x support (streamable HTTP transport)
• ✅ Real-time messaging using Twilio WhatsApp Sandbox
• ✅ Dynamic phone & message input (via HTML or CLI)
• ✅ Streaming response with text/event-stream
• ✅ Works with AI agents, CLI, or browser UI
• ✅ Optional: deployable to Render, Railway, Replit

---

🚀 Usage Guide

🔧 1. Setup

git clone https://github.com/your-username/whatsapp-mcp.git
cd whatsapp-mcp
python -m venv venv
venv\Scripts\activate  # or source venv/bin/activate
pip install -r requirements.txt

Create a .env file:

TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_twilio_auth_token
TWILIO_WHATSAPP_FROM=whatsapp:+14155238886

---

🧠 2. Start the Server

python server.py

You’ll see:

🔗 Server URL: http://localhost:8000/mcp
📦 Transport: Streamable-HTTP

---

🌐 3. Use the Browser UI

Open index.html in your browser.

Enter:

• 📱 Phone number (e.g., +91xxxxxxxxxx)
• 💬 Message

Click Send WhatsApp Message — and receive it instantly!

---

🧪 4. Test with curl

curl -X POST http://localhost:8000/mcp ^
  -H "Content-Type: application/json" ^
  -H "Accept: text/event-stream" ^
  -d "{\"tool\":\"send_whatsapp_message\", \"inputs\":{\"to\":\"+91xxxxxxxxxx\", \"body\":\"Hello from curl!\"}}"

✅ Replace +91xxxxxxxxxx with your verified WhatsApp number

---

📊 System Flow (Mermaid Diagram)

graph TD
  A[🧑 User] -->|Enters message & number| B[🌐 HTML UI]
  B -->|POST /mcp| C[🌀 FastMCP Server]
  C -->|calls| D[📲 Twilio API]
  D -->|sends| E[📱 WhatsApp Message]
  C -->|streams response| B

---

🧩 Tech Stack

• 🧠 FastMCP v2.x
• 🧪 Twilio WhatsApp API
• ⚙️ Python 3.11+
• 🌍 HTML + JS (Fetch API)
• 🔁 Server-Sent Events (SSE)

---

🛡️ Security Notes

• Never commit .env secrets
• Sandbox can only message verified users
• Upgrade to Twilio Business for full sending capabilities

---

🤖 Agent-Ready Example (Python)

from fastmcp import Client
from server import mcp

async with Client(mcp) as client:
    await client.call_tool("send_whatsapp_message", {
        "to": "+91xxxxxxxxxx",
        "body": "Triggered from an agent 🚀"
    })

---

💖 Author

Made with ❤️ by K Rajtilak