WaPulse WhatsApp MCP Server
A comprehensive Model Context Protocol (MCP) server that provides seamless integration with the WaPulse WhatsApp Web API. This server enables you to send messages, manage groups, handle files, and perform various WhatsApp operations through the MCP protocol.
Features
🚀 25 WhatsApp Tools Available
Messaging Tools (7)
send_whatsapp_message- Send text messages to individuals or groupssend_whatsapp_files- Send images, documents, and other filessend_whatsapp_audio- Send audio messages and voice notesload_chat_messages- Retrieve chat history and messagescheck_id_exists- Verify if a WhatsApp ID existsvalidate_phone_number- Validate phone number formatget_all_chats- Get all chat conversations
Group Management Tools (12)
create_whatsapp_group- Create new WhatsApp groupsadd_group_participants- Add members to groupsremove_group_participants- Remove members from groupspromote_group_participants- Promote members to admindemote_group_participants- Demote admins to membersleave_whatsapp_group- Leave a groupget_group_invite_link- Get group invite linkschange_group_invite_code- Generate new invite linksget_group_requests- View pending join requestsapprove_group_request- Approve join requestsreject_group_request- Reject join requestsget_all_groups- List all groups
Instance Management Tools (5)
create_instance- Create new WhatsApp instancesget_qr_code- Get QR code for WhatsApp Web connectionstart_instance- Start a WhatsApp instancestop_instance- Stop a WhatsApp instancedelete_instance- Delete a WhatsApp instance
General Tools (2)
get_wapulse_documentation- Access API documentationget_all_chats- Retrieve all chat conversations
Installation
Option 1: One-Click Cursor Installation (Easiest)
Click this link to automatically install in Cursor IDE:
📱 Install WaPulse MCP in Cursor
After clicking:
- Cursor will install the server automatically
- Edit your
~/.cursor/mcp.jsonfile - Replace
"enter-your-wapulse-token-here"with your actual WaPulse token - Replace
"enter-your-instance-id-here"with your actual instance ID - Restart Cursor
Option 2: NPX (Manual)
Install directly via NPX with your WaPulse credentials:
npx wapulse-whatsapp-mcp-server
Configuration via Environment Variables:
export WAPULSE_TOKEN="your-wapulse-token"
export WAPULSE_INSTANCE_ID="your-instance-id"
export WAPULSE_BASE_URL="https://wapulseserver.com:3003" # optional
npx wapulse-whatsapp-mcp-server
Configuration in MCP Client (Cursor):
Add to your mcp.json:
{
"mcpServers": {
"wapulse": {
"command": "npx",
"args": ["wapulse-whatsapp-mcp-server"],
"env": {
"WAPULSE_TOKEN": "your-wapulse-token",
"WAPULSE_INSTANCE_ID": "your-instance-id"
}
}
}
}
Option 3: Smithery Cloud
Install via Smithery cloud (requires Smithery account):
npx @smithery/cli@latest install @Quegenx/wapulse-whatsapp-mcp --client cursor
Option 4: Local Development
- Clone the repository:
git clone https://github.com/Quegenx/wapulse-mcp.git
cd wapulse-mcp
- Install dependencies:
npm install
- Build the project:
npm run build
- Configure your MCP client to use the built server at
dist/smithery-index.jswith your WaPulse credentials
Configuration
Required Configuration
wapulseToken- Your WaPulse API tokenwapulseInstanceID- Your WhatsApp instance ID
Optional Configuration
wapulseBaseUrl- WaPulse API base URL (defaults tohttps://wapulseserver.com:3003)
Example MCP Client Configuration
For Cursor IDE, add to your mcp.json:
{
"mcpServers": {
"wapulse-whatsapp": {
"command": "npx",
"args": [
"-y",
"@smithery/cli@latest",
"run",
"@Quegenx/wapulse-whatsapp-mcp",
"--key",
"your-smithery-key",
"--profile",
"your-profile"
]
}
}
}
Usage Examples
Send a WhatsApp Message
// Send a text message
await sendWhatsAppMessage({
to: "972512345678",
message: "Hello from MCP!",
type: "user"
});
Send Files
// Send an image with caption
await sendWhatsAppFiles({
to: "972512345678",
files: [{
file: "data:image/jpeg;base64,/9j/4AAQ...",
filename: "image.jpg",
caption: "Check out this image!"
}]
});
Create a WhatsApp Group
// Create a new group
await createWhatsAppGroup({
name: "My New Group",
participants: ["972512345678", "972587654321"]
});
Load Chat Messages
// Get chat history
await loadChatMessages({
id: "972512345678@c.us",
type: "user"
});
Phone Number Format
All phone numbers should be in international format without the + sign:
- ✅ Correct:
972512345678(Israel) - ✅ Correct:
14155552671(US) - ❌ Incorrect:
+972512345678 - ❌ Incorrect:
972-512-345-678
Error Handling
The server uses proper MCP error codes:
InvalidParams- For validation errors (invalid phone numbers, missing parameters)InternalError- For API failures or network issues
Development
Building
npm run build
Testing
npm test
Linting
npm run lint
API Documentation
The server includes a built-in documentation tool that provides comprehensive information about the WaPulse API:
await getWaPulseDocumentation({
section: "messaging", // overview, authentication, messaging, groups, instances, webhooks, errors, rate-limits, examples
search: "send message" // optional search term
});
Requirements
- Node.js 18+
- Valid WaPulse account and API credentials
- Active WhatsApp instance
Getting WaPulse Credentials
- Visit WaPulse.com
- Create an account and get your API token
- Create a WhatsApp instance and note the instance ID
- Use these credentials when installing the MCP server
Support
For issues related to:
- MCP Server: Open an issue on this repository
- WaPulse API: Contact WaPulse support
- WhatsApp Integration: Check WaPulse documentation
License
MIT License - see LICENSE file for details.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Built with ❤️ using the official Model Context Protocol SDK