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 groups
send_whatsapp_files - Send images, documents, and other files
send_whatsapp_audio - Send audio messages and voice notes
load_chat_messages - Retrieve chat history and messages
check_id_exists - Verify if a WhatsApp ID exists
validate_phone_number - Validate phone number format
get_all_chats - Get all chat conversations

Group Management Tools (12)

create_whatsapp_group - Create new WhatsApp groups
add_group_participants - Add members to groups
remove_group_participants - Remove members from groups
promote_group_participants - Promote members to admin
demote_group_participants - Demote admins to members
leave_whatsapp_group - Leave a group
get_group_invite_link - Get group invite links
change_group_invite_code - Generate new invite links
get_group_requests - View pending join requests
approve_group_request - Approve join requests
reject_group_request - Reject join requests
get_all_groups - List all groups

Instance Management Tools (5)

create_instance - Create new WhatsApp instances
get_qr_code - Get QR code for WhatsApp Web connection
start_instance - Start a WhatsApp instance
stop_instance - Stop a WhatsApp instance
delete_instance - Delete a WhatsApp instance

General Tools (2)

get_wapulse_documentation - Access API documentation
get_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.json file
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.js with your WaPulse credentials

Configuration

Required Configuration

wapulseToken - Your WaPulse API token
wapulseInstanceID - Your WhatsApp instance ID

Optional Configuration

wapulseBaseUrl - WaPulse API base URL (defaults to https://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

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

A Model Context Protocol server that integrates with WaPulse WhatsApp Web API, enabling users to send messages, manage groups, handle files, and perform various WhatsApp operations programmatically.

Related MCP Servers

Appwrite MCP Serverofficial
appwrite
A
security
A
license
A
quality
A Model Context Protocol server that allows AI assistants to interact with Appwrite's API, providing tools to manage databases, users, functions, teams, and other resources within Appwrite projects.
Last updated -
84
40
Python
MIT License
PayPal MCP Server
arbuthnot-eth
-
security
A
license
-
quality
A Model Context Protocol server that provides comprehensive integration with PayPal's APIs, enabling seamless interaction with payment processing, invoicing, subscription management, and business operations through a standardized interface.
Last updated -
TypeScript
Apache 2.0
MCP Evolution API
aiteks-ltda
-
security
A
license
-
quality
A Model Context Protocol server that enables Claude to interact with WhatsApp through the Evolution API, allowing for message sending, contact management, group operations, and WhatsApp instance administration.
Last updated -
1
10
TypeScript
MIT License
WhatsApp MCP Server
jlucaso1
-
security
F
license
-
quality
A Model Context Protocol server that connects your personal WhatsApp account to AI agents like Claude, enabling them to search messages, view contacts, retrieve chat history, and send messages via WhatsApp.
Last updated -
16
TypeScript

View all related MCP servers